媒体报价、上传和任务恢复
上传参考素材,获取美元报价,并在提交响应丢失后找回原任务。
上传参考素材
只传文件名即可申请签名的临时上传流程见上传素材。
- 用 Bearer API Key 调用
POST /api/v1/assets,传入fileName、contentType和以字节为单位的fileSize。 - 按返回的 Content-Type 把原始文件字节 PUT 到签名
uploadUrl。存储地址已通过签名授权,无需发送 i2v.ai API Key。 - 在 API 域名上向返回的
completeUrl发出 Bearer POST,拿到确认后的url,再传给模型的参考素材字段。收到asset_not_ready时,检查是否已上传,以及文件大小和类型是否与票据一致。上传票据 15 分钟内有效。
报价与提交
向 POST /api/v1/jobs/quote 发送与生成请求相同的 model 和 inputs。报价不创建任务,也不预占余额。核对返回的 maximum.amount 后,把你接受的美元上限作为 maxCostUsd,并将 expectedRevision 和原输入一起发给 createTask。提交时重新核对目录版本、账户价格和金额上限。价格或配置变化时,重新报价并核对预算。
curl --fail-with-body 'https://api.i2v.ai/api/v1/jobs/quote' \
-H "Authorization: Bearer $I2V_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"model":"seedance-2-mini","inputs":{"prompt":"镜头缓慢推进,展示木桌上的陶瓷杯"}}'每次新任务都生成一个幂等键,并保存原请求体和回执中的任务 ID。可参考中的提交示例。
丢失提交响应后的恢复
使用相同的 API Key 和原 Idempotency-Key,调用 GET /api/v1/jobs/submission。查询回执没有提交或预占操作。
| 回执 | 下一步 |
|---|---|
accepted | 保存返回的任务 ID,调用 recordInfo。 |
pending | 按 Retry-After 提示等待并查询原回执,保留原键。 |
retryable | 等待后用原请求体和原键重放。 |
rejected | 查看原错误或修正请求。修正后的请求需要新的幂等键。 |
| HTTP 404 | 核对原 API Key 和幂等键。重放同一次请求时仍使用原请求体和原键。 |
curl -i 'https://api.i2v.ai/api/v1/jobs/submission' \
-H "Authorization: Bearer $I2V_API_KEY" \
-H "Idempotency-Key: $I2V_IDEMPOTENCY_KEY"API 图像和视频任务可以返回 lifecycle.phase。原来的 status 字段可以继续使用。reconciling 表示任务仍在核对中,请按 pollAfterSeconds 查询原单。成功后的下载链接在 output[].url。生产环境优先使用,用轮询兜底。
取消尚未派发的任务
向 POST /api/v1/jobs/cancel 发送 {"taskId":"YOUR_TASK_ID"}。仅尚未被 worker 领取的账户内 API 图像和视频任务可以取消。取消成功后释放预占,安全重复调用会返回同一取消结果。查单和回调的 lifecycle.phase 为 cancelled,旧版 status 仍为 fail,查单错误码是 user_cancelled。收到 HTTP 409 时继续查原单。客户端终止等待不会取消生成。

