kie-models

在 KIE 上调用 AI 模型

KIE(api.kie.ai)托管了 200 多个图像、视频、音乐、语音和文本模型。本文覆盖模型发现, 以及走统一任务接口的模型的完整调用流程。

English: references/en.md

重要规则

1. 通过目录接口发现模型,不要凭记忆或训练数据写模型名。 目录持续变动——模型会新增、 改名、下线。你"记得"的名字可能已经不存在。
2. 调用前先拉 schema,并按它返回的 path 调用。 不是所有模型都走 /api/v1/jobs/createTask,同步聊天和 Gemini 系列模型各有自己的路径。 假设只有一条路径,必然出错。
3. 必填字段以 schema 的 required 数组为准。 各模型不一致。callBackUrl 对统一任务 接口是可选的,同步接口则没有这个字段。
4. 模型名里的斜杠不要 URL 编码。 wan/v2-2-t2v 原样拼进路径: /api/v1/models/wan/v2-2-t2v/schema。
5. 读 data 之前先判响应体里的 code。 所有接口都返回 {code, msg, data}。 HTTP 200 不代表调用成功。
6. schema 从不描述如何取结果。 见取结果。

先决条件

下文的代码片段都是 POSIX shell,需要 PATH 上有 curl 和 jq。多数系统不预装 jq:brew install jq、apt install jq 或 winget install jqlang.jq。

Windows 上请在 WSL 或 Git Bash 里运行。PowerShell 的 curl 是 Invoke-WebRequest 的别名,不接受这些参数——要写 curl.exe。cmd.exe 下片段必须重写,不能直接粘贴。

鉴权

每个请求都需要 bearer token:

Authorization: Bearer $KIE_API_KEY

API key 在 https://kie.ai/api-key 创建。base URL 是 https://api.kie.ai, schema 的 servers 字段里也有声明。

发现模型

查询目录

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/models'

可选筛选参数,可组合,均不分页:

参数	含义
taskType	任务类型。多值用逗号分隔。空格必须百分号编码——taskType=Text%20to%20Video,Image%20to%20Video。裸空格会让 curl 在发出请求前就失败(http=000)。用 + 也可以,或者交给 curl 编码:curl -G … --data-urlencode 'taskType=Text to Video'
provider	供应商名,如 Kling、Suno、Google
q	关键词模糊匹配

响应:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 202,
    "models": [
      {
        "model": "kling/v2-1-master-text-to-video",
        "slug": "kling/v2-1-master-text-to-video",
        "title": "Affordable Kling 2.1 Master API — Premium Text-to-Video Generation",
        "provider": "Kling",
        "taskType": ["Text to Video"],
        "description": "…",
        "pricingDesc": "A 5-second video costs 160 credits (0.80 USD), …"
      }
    ]
  }
}

• model 是后续所有接口使用的标识符。一段或两段(gpt-image-2-text-to-image、 wan/v2-2-t2v)。
• description 可能为 null,不要依赖它。
• pricingDesc 是文案不是数字,但与实际扣费一致,可以用来估算预算。
• total 会随模型的新增、改名、下线而变化。从中读到的任何数量(包括上面示例里的 那个)都只是某一时刻的快照。
• 筛选条件无匹配时返回 total: 0 和空的 models 列表;接口故障则以非 200 的 code 返回——空列表永远不是错误。

查报价与成功率

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/models/veo-3-1/price'

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/models/veo-3-1/success-rate'

price 返回 {model, pricingDesc},文案与目录接口同源。

success-rate 返回最近 24 小时,10 分钟一个采样点,最多 144 个:

{
  "model": "veo-3-1",
  "points": [
    {
      "start": "2026-09-08T07:30:00Z",
      "end": "2026-09-08T07:40:00Z",
      "successRate": 100.0,
      "errorRate": 0.0,
      "isNormal": true
    }
  ]
}

无流量的采样点,successRate 和 errorRate 为 null。points 为空列表表示没有监控 数据,不代表成功率为零。

查余额

提交任务前,把账户余额和模型 pricingDesc 对一下:

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/chat/credit'
# → {"code": 200, "msg": "success", "data": 2450}

data 是余额本身(数字)。目录接口返回的 pricingDesc 是单次调用的价格(例如 "A 5-second video costs 160 credits")。发 createTask 前先比一下——余额不足时任务 会返回 code 402。

读 schema

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/models/gpt-image-2-text-to-image/schema'

返回 {model, openapi},其中 openapi 就是 OpenAPI 文档本身,以 JSON 对象内联返回—— 直接读 data.openapi.paths,无需再解析一层。模型文档尚未同步时该字段为 null,此时 如实说明,不要凭空编一个调用路径。有值时它是该模型单个接口的完整 OpenAPI 3.1 文档, 也是以下信息的权威来源:

• 准确的调用路径与方法(paths)
• 每个请求字段的类型、说明、是否必填
• 投递到 callBackUrl 的回调 payload 结构(operation.callbacks)
• 业务错误码(401 未授权、402 额度不足、404 资源不存在、422 参数校验失败、 429 频率超限、433 子 key 超限、455 服务不可用)
• base URL(servers)与鉴权方式(components.securitySchemes)

部分模型的 input 是 oneOf 多选一结构(例如按 task-id 或按 image-url 两种入参形态)。 每个分支有各自的 required 列表——只满足其中一个分支,不要跨分支混填字段。

解析 $ref

$ref 未预内联。它们指向同一份文档的 components,一定能在文档内解析——但需要你 自己做解引用。

组件键名是字面量,必须精确匹配:

• 空格被百分号编码:#/components/schemas/response%20not%20with%20recordId。 查找前需对每段路径做 URL 解码。
• 有的键名以空格结尾:#/components/responses/Error 。匹配时不要 trim 空白。

两类模型形态

看 paths 区分:

paths 的键	形态
/api/v1/jobs/createTask	任务制。 提交拿 taskId,再轮询取结果。下文详述。
其他	同步返回的 chat/completions 接口,结果直接在响应体里。见统一接口之外的模型。

图/视频模型的文件上传

目录里约 78 个模型(46 个图生视频、32 个图生图)需要在 input 里传一个文件 URL。 不同模型的字段名不一致——image_url、input_image、image、video_url、 first_frame_image 等等——必须去 schema 的 input 里查准确字段名,不要猜。

用户已经有公开 HTTPS URL 时直接用。没有就先把文件传到 KIE 的临时文件服务,拿到 URL 再塞进 input。

上传接口在另一个域名:https://kieai.redpandaai.co,不是 api.kie.ai。 沿用同一个 bearer token。上传的文件 24h 后自动删除——够用来立刻发一次任务,但不是长期 存储。

接口	场景
POST /api/file-base64-upload	文件在内存里,小(≤10MB)。JSON body,base64 或 data URL
POST /api/file-stream-upload	文件在磁盘上,大(>10MB)。multipart/form-data
POST /api/file-url-upload	把一个公开 URL 转存到 KIE 的 CDN。JSON body

三个接口返回同一结构:

{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "downloadUrl": "https://tempfile.redpandaai.co/…/my-image.png",
    "fileName": "my-image.png",
    "filePath": "images/user-uploads/my-image.png",
    "fileSize": 154832,
    "mimeType": "image/png",
    "uploadedAt": "2026-09-22T12:00:00.000Z"
  }
}

把 data.downloadUrl 填到模型 input 里对应的字段——具体字段名以 schema 为准。

公共 body 字段(三个接口都有):uploadPath——必填,前后都不带斜杠(如 images/user-uploads);fileName——可选,包含扩展名。接口独有:base64Data (base64)、file(stream 的表单字段)、fileUrl(url)。

# base64:内存里的小文件
curl -s -X POST 'https://kieai.redpandaai.co/api/file-base64-upload' \
  -H "Authorization: Bearer $KIE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"base64Data": "data:image/png;base64,iVBORw0K…",
       "uploadPath": "images/user-uploads",
       "fileName": "input.png"}'

# stream:磁盘上的大文件
curl -s -X POST 'https://kieai.redpandaai.co/api/file-stream-upload' \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -F "file=@/path/to/input.png" \
  -F "uploadPath=images/user-uploads" \
  -F "fileName=input.png"

# url 转存:从其他站点抓到 KIE
curl -s -X POST 'https://kieai.redpandaai.co/api/file-url-upload' \
  -H "Authorization: Bearer $KIE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"fileUrl": "https://example.com/photo.jpg",
       "uploadPath": "images/downloaded"}'

拿到 downloadUrl 直接喂给 createTask:

UPLOAD_URL=$(curl -s -X POST 'https://kieai.redpandaai.co/api/file-stream-upload' \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -F "file=@/path/to/input.png" -F "uploadPath=images/user-uploads" \
  | jq -r .data.downloadUrl)

curl -s -X POST 'https://api.kie.ai/api/v1/jobs/createTask' \
  -H "Authorization: Bearer $KIE_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"model\":\"kling/v2-1-master-image-to-video\",
       \"input\":{\"image_url\":\"$UPLOAD_URL\",\"prompt\":\"…\"}}"

调用模型

对 schema 中 paths 为 /api/v1/jobs/createTask 的模型:

curl -s -X POST 'https://api.kie.ai/api/v1/jobs/createTask' \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2-text-to-image",
    "input": {
      "prompt": "A single red maple leaf resting on wet slate, macro photograph",
      "resolution": "1K",
      "aspect_ratio": "1:1"
    }
  }'

请求体字段:

字段	必填	说明
model	是	与目录接口返回的完全一致
input	是	嵌套对象。 内部字段来自 schema,各模型不同
callBackUrl	否	填了则任务完成时 KIE 会 POST 结果到此地址。payload 结构见 schema 的 callbacks

响应:

{"code": 200, "msg": "success", "data": {"taskId": "e931f4f2…", "recordId": "e931f4f2…"}}

用 taskId 轮询。recordId 不是轮询用的键。

取结果

curl -s -H "Authorization: Bearer $KIE_API_KEY" \
  'https://api.kie.ai/api/v1/jobs/recordInfo?taskId=e931f4f2…'

终态响应:

{
  "code": 200,
  "data": {
    "taskId": "e931f4f24b0f6d5bc4744c719d3f67f3",
    "model": "gpt-image-2-text-to-image",
    "state": "success",
    "successFlag": 1,
    "costTime": 59,
    "creditsConsumed": 3.0,
    "createTime": 1788941299171,
    "completeTime": 1788941358629,
    "failCode": null,
    "failMsg": null,
    "resultJson": "{\"resultUrls\":[\"https://…/images/….png\"]}",
    "response": {"resultUrls": ["https://…/images/….png"]}
  }
}

状态机

state	successFlag	是否终态
waiting	0	否
queuing	0	否
generating	0	否
success	1	是
fail	3	是

按 state 轮询。遇 success 或 fail 停止,其余一律视为仍在运行。fail 时读 failCode 和 failMsg。

一个可用的轮询循环。它把响应写进文件而不是变量,原因见下方警告:

out=$(mktemp)
deadline=$(( $(date +%s) + 300 ))
while :; do
  if curl -sf -H "Authorization: Bearer $KIE_API_KEY" \
       "https://api.kie.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" -o "$out"; then
    [ "$(jq -r .code "$out")" = 200 ] || { jq -r .msg "$out" >&2; break; }
    case $(jq -r .data.state "$out") in
      success) jq -r '.data.response.resultUrls[]?' "$out"; break ;;
      fail)    jq -r '.data.failMsg' "$out" >&2; break ;;
    esac
  fi
  [ "$(date +%s)" -ge "$deadline" ] && { echo '等待超时' >&2; break; }
  sleep 3
done
rm -f "$out"

3 秒是合适的间隔。recordInfo 限流为每秒 10 次,一张 1K 图端到端通常在一分钟左右。 300 秒的截止时间适用于图像任务——视频和音乐耗时更长,要调大;没有它,遇到永远到不了 终态的任务就会无限空转。curl -sf 把 HTTP 层的失败变成一次重试,而不是拿空文件去解析 报错;code 不是 200 就停下并打印 msg——否则一个被拒绝的请求会被当成"仍在运行"。 resultUrls[]? 里的 ? 保证循环对 Suno 系列同样可用——它们的结果在别的字段,见 读取产出。所有出口都是 break,既能直接粘进交互式 shell,也保证走到 rm。

不要用 echo 把 KIE 的响应喂给 jq。 recordInfo 返回的 param 字段是 JSON 套 JSON,原始字节含有 \\\";zsh、dash、busybox ash 会展开这些转义,jq 随即报 Invalid numeric literal。bash 的内建 echo 不展开,所以换一个 shell 运行之前可能 都不会暴露。按上面的写法把响应落到文件,或者用 printf '%s' "$r" | jq …。

读取产出

• response 是 resultJson 解析后的结果,优先用它。
• 多数模型把生成文件放在 response.resultUrls。Suno 的音频生成类任务使用 自己的结果结构:generate、extend、sounds 以及 upload-and-cover/extend 系列的音轨在 response.data[].audio_url,每首附带 stream_audio_url、封面 image_url、title 和 duration。Suno 的文本与分析类任务(歌词生成、MIDI 提取)返回 response.resultObject,歌词在 resultObject.lyricsData[].text。 Suno 的文件工具类任务(WAV 转换、人声分离、封面图、音乐视频)和其他模型一样用 resultUrls。所有模型的 state / successFlag 状态机是一致的。任务成功但 没有 resultUrls 时,按上述结构从 response 中取结果。
• 生成的媒体文件保存 14 天后自动删除,需要的内容请下载保存,不要把 URL 当作 长期地址。日志记录(即 recordInfo 返回的文本与元数据)保存 2 个月。

拿产物的直接下载链接

有时 resultUrls 里的链接不能直接给浏览器或下游系统流式下载。这个接口把它转成 一个短期有效的直下载链接:

curl -s -X POST 'https://api.kie.ai/api/v1/common/download-url' \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://tempfile.redpandaai.co/…/output.png"}'
# → {"code": 200, "msg": "success", "data": "https://tempfile.…"}

• 入参 url 必须是 KIE 自家的 URL(resultUrls 里的,或上传接口返回的 downloadUrl)。外部 URL 直接 422。
• 返回的下载链接有效期 20 分钟。它不延长底层文件的 14 天保存期,只是给一条 新鲜的直下载链接。
• data 是字符串本身(URL),不是对象。

统一接口之外的模型

不是所有模型都走 /api/v1/jobs/createTask。其余的是同步接口—— /claude/v1/messages、/codex/v1/responses、/grok/v1/responses 以及 Gemini 系列路径。按 schema 的 paths 提交、按 schema 描述构造请求体,结果直接在响应体里 返回——没有任务可轮询,也没有单独的取结果步骤。

限流

以下是默认额度。超限的请求会被拒绝,code 为 429——注意 429 在响应体里,HTTP 状态可能仍是 200,判 code 而不是状态行。被拒绝的请求不会进入队列,需要自行重试。 如需更高额度,可联系官方支持申请。

接口	限流	计数维度
models、schema、price、success-rate	1 次 / 秒,四个接口共用一份额度	账户
createTask	20 次 / 10 秒	账户
recordInfo	10 次 / 秒	taskId

createTask 这一档通常支持 100 个以上任务同时运行。发现类接口的共享额度是最紧的一档: 一次目录调用和一次 schema 调用消耗的是同一份每秒 1 次的配额,连续做发现类调用时, 请求间隔至少 1.1 秒。目录接口一次就返回全量——需要多种筛选视图时,不带参数拉一次、 在本地过滤,别为每个筛选条件各花一格配额。

常见错误

最常见的失败就是违反重要规则,那六条这里不再重复。下面是容易忽略的响应 格式细节。

1. openapi 可能为 null。 模型可能已进目录但文档尚未同步。读 data.openapi.paths 前先判 null。
2. param.input 回来是字符串。 请求时传的是对象,回显的是 JSON 文本,读回自己 的参数要再解析一层。
3. progress 不填充。 recordInfo 有这个字段,但不会填值。轮询 state。
4. 结果 URL 14 天后失效。 拿到就下载,不要存 URL。
5. 对同一个 taskId 轮询超过 10 次/秒会被限流。
6. echo 会破坏响应。 zsh、dash、busybox ash 都会展开 param 里的反斜杠转义, jq 随即解析失败。改用文件或 printf '%s'。
7. 查询串里的裸空格会让 curl 在发出请求前就失败。 要百分号编码: taskType=Text%20to%20Video。
8. response 不一定是 resultUrls。 Suno 音频生成类任务的音轨在 response.data[].audio_url,文本与分析类任务的结果在 response.resultObject。见读取产出。