# 媒体报价、上传和任务恢复

## 上传参考素材

只传文件名即可申请签名的临时上传流程见[上传素材](/docs/uploads)。

1. 用 Bearer API Key 调用 `POST /api/v1/assets`，传入 `fileName`、`contentType` 和以字节为单位的 `fileSize`。
2. 按返回的 Content-Type 把原始文件字节 PUT 到签名 `uploadUrl`。存储地址已通过签名授权，无需发送 i2v.ai API Key。
3. 在 API 域名上向返回的 `completeUrl` 发出 Bearer POST，拿到确认后的 `url`，再传给模型的参考素材字段。收到 `asset_not_ready` 时，检查是否已上传，以及文件大小和类型是否与票据一致。上传票据 15 分钟内有效。

## 报价与提交

向 `POST /api/v1/jobs/quote` 发送与生成请求相同的 `model` 和 `inputs`。报价不创建任务，也不预占余额。核对返回的 `maximum.amount` 后，把你接受的美元上限作为 `maxCostUsd`，并将 `expectedRevision` 和原输入一起发给 `createTask`。提交时重新核对目录版本、账户价格和金额上限。价格或配置变化时，重新报价并核对预算。

```bash
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。可参考[快速开始](/docs)中的提交示例。

## 丢失提交响应后的恢复

使用**相同的 API Key 和原 Idempotency-Key**，调用 `GET /api/v1/jobs/submission`。查询回执没有提交或预占操作。

| 回执 | 下一步 |
| --- | --- |
| `accepted` | 保存返回的任务 ID，调用 `recordInfo`。 |
| `pending` | 按 `Retry-After` 提示等待并查询原回执，保留原键。 |
| `retryable` | 等待后用原请求体和原键重放。 |
| `rejected` | 查看原错误或修正请求。修正后的请求需要新的幂等键。 |
| HTTP 404 | 核对原 API Key 和幂等键。重放同一次请求时仍使用原请求体和原键。 |

```bash
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`。生产环境优先使用[签名 Webhook](/docs/webhooks)，用轮询兜底。

## 取消尚未派发的任务

向 `POST /api/v1/jobs/cancel` 发送 `{"taskId":"YOUR_TASK_ID"}`。仅尚未被 worker 领取的账户内 API 图像和视频任务可以取消。取消成功后释放预占，安全重复调用会返回同一取消结果。查单和回调的 `lifecycle.phase` 为 `cancelled`，旧版 `status` 仍为 `fail`，查单错误码是 `user_cancelled`。收到 HTTP 409 时继续查原单。客户端终止等待不会取消生成。