# 生成与恢复

## 规划首个任务

1. 用 `recommend_models` 按用途和限制选型，或用 `get_model_params` 查询已指定的模型。`list_models` 可按 `mediaType`、`category`、`search`、`limit` 和 `offset` 筛选或分页。
2. 按所选模型的契约准备入参。可使用可访问的 HTTPS 素材地址，或按下面的步骤上传已经授权使用的文件。
3. 用 `modelId` 和 `inputs` 调用 `prepare_generation`，核对 `maximumReservation`、`normalized` 和 `expectedRevision`。遇到 `review_adjustments` 或 `over_budget` 先解决再继续。预检会检查参数和价格，全程无需上传或预留余额。
4. 用户批准后，调用 `create_task`，带上同一份 `modelId` 和 `inputs`、批准的 `maxCostUsd`、`expectedRevision` 和稳定的 `idempotencyKey`。需要支持找回的 OAuth 提交，还应设置 `recoveryScope: "connection"`。保留任务 ID 和幂等键。
5. 用 `get_task` 查询同一个 ID，逐步拉长轮询间隔。任务成功后使用返回的产物地址，也可用本地 stdio 将结果保存到工作区。

预算上限用美元小数字符串，例如 `"0.25000000"`。模型版本变化时需重新预检。提交时服务端会重新读取当前账户报价，超过预算上限时拒绝提交。符合条件的免费模型权益会返回明确的零美元报价。详情见[美元余额与计费](/docs/billing)。

## 上传参考素材

用 `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` 表示任务仍在等待或运行。客户端的等待结束后，任务仍可继续。通用错误语义见[错误与重试](/docs/errors)。

## 接收完成回调

需要服务端通知时，先在[开发者设置](/settings/developer)配置签名密钥，再把 `callBackUrl` 与 `modelId`、`inputs` 一起传给 `create_task`。处理回调前校验签名并按事件 ID 去重。回调投递和任务结算分别处理。参阅[任务回调](/docs/webhooks)与 [REST 媒体流程](/docs/media-workflow)。