生成与恢复
对实际入参询价,在批准的美元预算内提交,并在超时后找回原任务。
规划首个任务
- 用
recommend_models按用途和限制选型,或用get_model_params查询已指定的模型。list_models可按mediaType、category、search、limit和offset筛选或分页。 - 按所选模型的契约准备入参。可使用可访问的 HTTPS 素材地址,或按下面的步骤上传已经授权使用的文件。
- 用
modelId和inputs调用prepare_generation,核对maximumReservation、normalized和expectedRevision。遇到review_adjustments或over_budget先解决再继续。预检会检查参数和价格,全程无需上传或预留余额。 - 用户批准后,调用
create_task,带上同一份modelId和inputs、批准的maxCostUsd、expectedRevision和稳定的idempotencyKey。需要支持找回的 OAuth 提交,还应设置recoveryScope: "connection"。保留任务 ID 和幂等键。 - 用
get_task查询同一个 ID,逐步拉长轮询间隔。任务成功后使用返回的产物地址,也可用本地 stdio 将结果保存到工作区。
预算上限用美元小数字符串,例如 "0.25000000"。模型版本变化时需重新预检。提交时服务端会重新读取当前账户报价,超过预算上限时拒绝提交。符合条件的免费模型权益会返回明确的零美元报价。详情见。
上传参考素材
用 fileName、contentType 和 fileSize 调用 create_upload_url。按返回的 Content-Type 将原始字节 PUT 到临时地址,然后用 assetId 调用 complete_upload。验证成功后的素材地址可用于生成入参。API Key 只发给 i2v.ai,签名上传地址自带凭据。本地 stdio 的 upload_file 可对允许的工作区路径自动完成这些动作。
响应丢失后查回原任务
有任务 ID 时,调用 get_task。只有原幂等键时,用相同 API Key 或原 OAuth 客户端调用 recover_submission。OAuth 任务需要在首次提交时启用客户端恢复范围。
| 回执状态 | 下一步 |
|---|---|
accepted | 用返回的任务 ID 继续查单。 |
pending 或 not_found | 继续查询原提交,受理状态未明时保留原幂等键。 |
retryable | 按提示等待,再带相同请求内容与幂等键重试。 |
rejected | 核对原错误后,再决定如何修正。 |
重放时保持所有提交字段一致,包括模型版本、预算和恢复范围。waiting 或 generating 表示任务仍在等待或运行。客户端的等待结束后,任务仍可继续。通用错误语义见。
接收完成回调
需要服务端通知时,先在配置签名密钥,再把 callBackUrl 与 modelId、inputs 一起传给 create_task。处理回调前校验签名并按事件 ID 去重。回调投递和任务结算分别处理。参阅与 。

