数据,不代表成功率为零。

查余额

提交任务前,把账户余额和模型 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。见读取产出。