文件与输入
通过公开 HTTPS 链接、/v1/files 上传接口或小体积 data URI 传入参考图、首尾帧、参考视频与音频。
传入媒体文件的三种方式
任务 input 中的任意文件类字段(参考图、视频首尾帧、参考视频、音频)都支持以下三种方式:
- 公开
https://URL:Kerox 可直接拉取的公开链接。 - 通过
POST /v1/files上传后的 URL:单文件最大 200 MB,保留 7 天。 - 内联 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返回 HTTP422(invalid_parameter)。每个模型只支持其中一部分:格式和分辨率的限制见模型的input_schema。