Skip to Content

文件与输入

通过公开 HTTPS 链接、/v1/files 上传接口或小体积 data URI 传入参考图、首尾帧、参考视频与音频。

传入媒体文件的三种方式

任务 input 中的任意文件类字段(参考图、视频首尾帧、参考视频、音频)都支持以下三种方式:

  1. 公开 https:// URL:Kerox 可直接拉取的公开链接。
  2. 通过 POST /v1/files 上传后的 URL:单文件最大 200 MB,保留 7 天。
  3. 内联 base64 data URI(data:image/png;base64,...):单次请求内所有内联文件合计不超过 3 MB(整包请求体不超过 4 MB)。

预签名直传(大文件推荐)

以 JSON 提交文件元信息到 POST /v1/files,接口会返回有效期 15 分钟的预签名 upload_url、上传时要带的请求头 upload_headers,以及后续可用的 url。带上这些请求头把文件 PUT 到 upload_url 后,就可以把 url 放进任务参数。上传地址是按你声明的 content_type 和 size 签名的,所以 size 必须是文件的准确字节数,大小或类型不一致会被拒绝。

# 1. 获取预签名 PUT 地址。"size" 是文件的准确字节数
RESPONSE=$(curl -s -X POST https://api.kerox.ai/v1/files \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"frame.png\",
    \"content_type\": \"image/png\",
    \"size\": $(wc -c < frame.png | tr -d ' ')
  }")
printf '%s\n' "$RESPONSE"

# 2. 从返回里取出 upload_url,把文件内容 PUT 过去
UPLOAD_URL=$(printf '%s' "$RESPONSE" | sed -n 's/.*"upload_url": *"\([^"]*\)".*/\1/p')
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @frame.png

小文件直接表单上传(≤ 4 MB)

4 MB 以内的文件可直接以 multipart/form-data 提交,表单字段名为 file,接口会立即返回 status: "ready" 的文件对象。

curl -X POST https://api.kerox.ai/v1/files \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -F "file=@frame.png"

状态查询与保留期

  • 可调用 GET /v1/files/{id} 查看预签名上传的状态:文件传完之前是 "pending",传完后变成 "ready"。
  • 上传的文件会在 7 天后自动删除。
  • 上传接口接受这些类型:image/jpeg、image/jpg、image/png、image/webp、image/bmp、image/tiff、image/gif、image/avif、image/heic、image/heif、video/mp4、video/quicktime、video/webm、audio/wav、audio/x-wav、audio/wave、audio/vnd.wave、audio/mpeg、audio/mp4。其他 content_type 返回 HTTP 422(invalid_parameter)。每个模型只支持其中一部分:格式和分辨率的限制见模型的 input_schema。