> 来源页面：https://iwkey.com/docs/video-model/（本页的 Markdown 版本）

文档 · 视频模型

# 视频模型 API 平台化接入指南

把视频生成接口接进你自己的产品或工具，供你的用户或团队使用。

已经在用火山方舟原生请求格式的开发者，可以直接使用本平台的方舟兼容入口（`POST /videos/api/v3/contents/generations/tasks`）；与方舟原生的具体差异见下方「[5.9 方舟兼容入口：与方舟原生的差异](https://iwkey.com/docs/video-model/#ark-diff)」。

## 01 三分钟跑通第一条视频

**想先感受一下？**用你的 API Key 在[视频工作台](https://iwkey.com/videos/create.html)直接生成一段视频，不用写代码。

最小闭环三步：**提交 → 轮询 → 取片**。

⚠️ 生成是**异步**的，出片耗时因模型、时长与画面复杂度而异。提交返回的是任务号，不是视频，请轮询响应里的 `poll_url` 获取结果。**不要同步等待**。

第零步：先建一把 API Key

在控制台「令牌」页新建即可。**分组只决定文本类模型的计价档位**，视频模型不走分组，保持默认的 `auto` 即可；任何一把 key 都能调用本文列出的全部视频模型。**价格按客户折扣计算，实际以 `/estimate` 当次返回为准**——同一模型不同客户看到的金额可能不同。

🔴 密钥上的「IP 白名单」**对视频接口生效**：来源不在名单内会返回 `403 ip_not_allowed`，出口 IP 不固定时建议留空。「可用模型」白名单不作用于视频接口。

第一步：提交生成任务

**curl 示例 · 提交任务**

```bash
curl https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "一段海上日出，镜头缓缓推近",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

响应里 `status` 初始为 `queued`（这一态可能极短，提交响应里直接看到 `running` 也正常），随后转 `running`；`poll_url` 就是下一步要轮询的地址：

**响应示例 · 提交成功**

```
{
  "job_id": "...",
  "status": "queued",
  "poll_url": "https://iwkey.com/videos/v1/videos/jobs/<job_id>",
  "created_at": "2026-08-22T10:03:11Z"
}
```

（可选）提交前先估价

请求字段与提交完全相同，只是把路径换成 `/generations/estimate`——**不建任务、不扣费、不触发生成**：

**响应示例 · 估价（doubao-seedance-2.0 · 720p · 5 秒，仅示例，实际金额以 /estimate 当次返回为准）**

```
{
  "model": "doubao-seedance-2.0",
  "estimated_cost": 0.8132,
  "estimated_cost_cny": 5.69,
  "fx_cny_per_usd": 7,
  "currency": "USD",
  "basis": "pre_hold",
  "final_cost_may_adjust": true
}
```

第二步：轮询任务状态

把上一步响应里的 `poll_url` 原样拿来请求即可：

**curl 示例 · 轮询**

```bash
curl <poll_url> \
  -H "Authorization: Bearer <你的 API Key>"
```

第三步：取片

`status` 变成 `completed` 后，`video_url` 就是可下载的视频直链：

**响应示例 · 已完成，可取片**

```
{
  "job_id": "...",
  "status": "completed",
  "model": "doubao-seedance-2.0",
  "video_url": "<生成引擎官方直链>",
  "platform_video_url": null,
  "expires_at": "2026-08-23T10:05:40Z",
  "cost_final": 0.81,
  "duration_ms": 118342,
  "metadata": { "duration": 5, "resolution": "720p" }
}
```

⚠️ **`video_url` 会失效**，请及时下载保存，不要依赖它长期可访问；**具体失效时间以同一响应里的 `expires_at` 为准**（不同模型所在的上游通道有效期不同，多数约 24 小时，请以每次返回的值为准）。

当前可用视频模型

| 模型 | 调用名（`model` 字段填这个） | 支持分辨率 |
| --- | --- | --- |
| Seedance 2.0 | `doubao-seedance-2.0` | 480p / 720p / 1080p / 4k |
| Seedance 2.0 极速 | `doubao-seedance-2.0-fast` | 480p / 720p |
| Seedance 2.5 | `doubao-seedance-2.5` | 480p / 720p / 1080p |
| MiniMax H3 | `MiniMax-H3` | 768p / 2k（须小写；`768P` / `2K` 会被拒） |

以上为当前可用的视频模型；完整、实时的清单以[模型市场](https://iwkey.com/models)为准。视频模型不在文本网关的 `GET /v1/models` 里。

## 02 参考图

🔴 **API 提交参考图，请提供公网可访问的 URL，放进 `image_urls`。**

真人形象的图：先用这个 URL 建素材，拿到 `asset://<素材ID>` 后在生成请求里引用它，见下节「素材库：真人形象的唯一通道」。

（本平台另提供一个上传接口，供视频工作台在用户从本地选图时使用；平台化 API 接入用不到它，见「接口参考 → 5.8」。）

⚠️ **像素上限**：本平台**上传预检**按单张图宽×高不超过 **3600 万像素**拦截（该值取自现役供应通道 2026-08-18 生产实测的真实拒绝阈值，不同供应通道的生成时上游限制可能不同，以生成时返回的错误信息为准）。手机原图常见 6048×8064（约 4900 万像素），**会超限**。超限的图片会导致任务失败，预扣自动退回。

**Base64**：与生成引擎官方一致，图片 / 音频可以直接写 `data:image/<格式>;base64,…` / `data:audio/<格式>;base64,…`（格式小写；图片 jpeg、png、webp、bmp、tiff、gif、heic、heif，单张小于 30 MB；音频 wav、mp3，单段不超过 15 MB；整个请求体不超过 64 MB）。任务详情里显示的是平台生成的链接。格式或大小不符返回 `invalid_inline_media`，不扣费。参考视频不支持 Base64。大文件建议先上传或入素材库，再传链接。

⚠️ 单次请求的参考素材上限按模型不同：**Seedance 2.0 系列**最多 9 张参考图、3 段参考视频、3 段参考音频；**Seedance 2.5** 最多 30 张参考图、10 段参考视频、10 段参考音频。

## 03 素材库：真人形象的唯一通道

为什么存在

**目前适用于 Seedance 2.0 和 Seedance 2.5：**这两个模型对包含真人形象的参考图有内容审核，**直接传图片链接会被拒**。素材库是引用真人形象的通道：先把形象注册为素材，再在生成请求里引用它。其他模型是否有同样的审核，请以生成请求实际返回的错误码为准（未触发该审核的模型不会返回 `input_image_real_person`）。

什么时候必须用

Seedance 2.0 和 Seedance 2.5 的参考图里有**真人脸**时。参考素材含真实人脸时必须走素材库注册；直接传人脸图片 URL 会被审核拦截。

三步

- 拿到一个图片或视频的公网链接（自己的链接，或用上传接口拿一个）
- 调建素材接口，传入链接与名称（视频素材加 `"kind": "video"`，音频素材加 `"kind": "audio"`；**视频、音频只收公网可直下链接，没有上传接口**）→ 得到素材 ID。**视频、音频素材是否支持取决于当前素材库通道**：不支持时返回 `asset_kind_unsupported`（400，不扣费），此时改为在生成请求里直接传公网直链，不走素材库
- 在生成请求的 `image_urls`（视频素材则 `video_urls`）里写 `asset://<素材ID>`

⚠️ 建素材后有一个**短暂的处理期**（通常十秒内），处理完成才可用于生成。拿建素材响应里的 `id`，**按 id 单独查这一张**（`GET /videos/v1/videos/assets/<id>`），轮询到 `status` 为 `Active` 再提交生成请求，不要按固定等待时长猜。

推荐流程（多张图一起用时）

- 把要用的几张图**一起登记**（每张各调一次建素材接口，不必等上一张就绪），记下每张的 `id`
- **每 2～3 秒**按 `id` 逐张查一次状态，地址就是：
  `GET https://iwkey.com/videos/v1/videos/assets/<id>`（curl 示例见下方）
- 查到 `status` 为 `Active` → 这张可以提交生成
- 查到 `Failed` → 按 `error.code` 处理，见 [6.1 错误码表](https://iwkey.com/docs/video-model/#error-codes-request)
- 为整轮登记设一个**总上限 120 秒**；超过再按失败处理。多数几秒就绪，个别会更久，**120 秒内不要只因为等得久就判失败**

🔴 **轮询退出条件必须覆盖两个终态**：`Active`（处理完成，可以提交生成）与 `Failed`（处理失败，按 `error.code` 处理）。

单张查询接口：`GET /videos/v1/videos/assets/<id>`

**curl 示例 · 按 id 查一张素材**

```bash
BASE="https://iwkey.com"
curl "$BASE/videos/v1/videos/assets/<id>" \
  -H "Authorization: Bearer <你的 API Key>"
```

**响应示例（就绪）**

```
{
  "id": "...",
  "asset_id": "...",
  "ref": "asset://<素材ID>",
  "name": "服务员小李",
  "status": "Active",
  "kind": "image",
  "usable": null,
  "source_url": "<你的公网图片链接>",
  "created_at": "2026-09-15T13:37:02Z",
  "error": null
}
```

路径里的 `<id>` 用建素材响应里的 `id`；直接用 `asset_id` 也可以。返回字段与列表接口里的单条完全一样。**不属于你的 id、不存在的 id、已删除的素材，一律返回 404**。
（可选）在多个模型之间来回切换时，可加 `?model=<模型名>` 让 `usable` 给出 true/false（不带或填了未知模型名时为 `null`）。
`status` 为 `Failed` 时多一个 `error` 对象 `{code, message, details}`，说明上游为什么判它失败（其余状态为 `null`）：`asset_processing_timeout` 是上游处理超时，删掉这份素材后重新登记即可；`asset_processing_failed` 可删掉后重新登记，再次失败就换一份文件。`details.upstream_message` 是上游原话（已过滤，可能没有）。

🔴 **列表接口用于管理素材，不要用它轮询状态；轮询请用上面的单张查询接口。**

⚠️ `Failed` 请按 `error.code` 处理：`asset_processing_timeout` 与 `asset_processing_failed` 可删掉后重新登记，再次失败就换一份文件；其余各码的原因与处理方法见 [6.1 错误码表](https://iwkey.com/docs/video-model/#error-codes-request)。较早失败的素材可能没有 `details.upstream_message`。

（可选）接入前先查一次该模型能不能用素材库

**curl 示例 · 查询能力**

```bash
BASE="https://iwkey.com"
curl "$BASE/videos/v1/videos/assets/capability?model=doubao-seedance-2.0" \
  -H "Authorization: Bearer <你的 API Key>"
```

**响应示例**

```
{
  "enabled": true,
  "upload_max_bytes": 31457280,
  "upload_max_pixels": 36000000
}
```

第一步：建素材

**curl 示例 · 建素材**

```bash
BASE="https://iwkey.com"
curl "$BASE/videos/v1/videos/assets" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "<你的公网图片链接>",
    "name": "服务员小李"
  }'
```

**响应示例**

```
{
  "id": "...",
  "asset_id": "...",
  "ref": "asset://<素材ID>",
  "name": "服务员小李",
  "status": "Processing",
  "usable": false,
  "source_url": "<你的公网图片链接>",
  "created_at": "2026-08-22T10:00:02Z",
  "error": null
}
```

素材状态：`Processing`（处理中）→ `Active`（处理完成）/ `Failed`（处理失败）。
⚠️ **上面示例里 `status` 还是 `Processing`，这一次响应不能直接拿去提交生成**——请拿响应里的 `id` 按 id 轮询，查到 `status` 为 `Active` 再提交。`doubao-seedance-2.0` / `doubao-seedance-2.0-fast` 必须等到处理完成才能引用；`MiniMax-H3` 例外，登记后即可引用，不看这个状态。

拿不准就调 `GET /videos/v1/videos/assets/capability?model=<模型名>`，`enabled` 会直接告诉你这个模型能不能引用素材。

第二步：在生成请求里引用它

把上一步拿到的 `ref`（`asset://<素材ID>`）放进 `image_urls`，和普通图片链接一样使用：

**curl 示例 · 引用素材生成**

```bash
curl https://iwkey.com/videos/v1/videos/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "这位人物走进店铺，面带微笑向镜头问好",
    "image_urls": ["asset://<素材ID>"],
    "resolution": "720p",
    "duration": 5
  }'
```

## 04 人物命名与位置语法

多个参考图同时出现时，可以在提示词里指明"让**这个人**做什么"。

🔴 **接口上必须使用位置语法 `@图片1`、`@图片2`（写成 `@图片 1` 带空格也可以）**，编号对应 `image_urls` 数组的顺序（从 1 开始）。**目前仅 `Seedance 2.0` 和 `Seedance 2.5` 支持这套 @ 语法。**`MiniMax-H3` 不解析它：多张参考图按 `image_urls` 的数组顺序与每项的 `role` 字段区分（见「参考图」一节），提示词里不能用 @ 绑定角色。

⚠️ **接口只识别 `@图片1`、`@图片2` 这类位置语法，不解析自定义人名。**写入人名会被当作普通提示词文字，人物绑定不生效；需要支持人名输入的，请在提交前映射为 `@图片N`。

⇒ 如果你想让使用者用名字，**替换要在你自己的产品里做**：维护"名字 → 这张图排第几"的映射，提交前替换成 `@图片N`。

## 05 接口参考

**鉴权**：所有接口用 `Authorization: Bearer <你的密钥>`。

**错误信封**（本节 REST 接口与方舟兼容入口统一）：

**错误响应结构**

```
{ "error": { "code": "稳定码", "message": "说明", "type": "错误类别",
             "field": "出问题的字段（可选）", "details": { } } }
```

请**按 `code` 分支处理**，不要匹配 `message` 文字——文案可能调整，`code` 稳定。

5.1 提交生成任务 · `POST /videos/v1/videos/generations`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | ✅ | 模型名，≤100 字符 |
| `prompt` | string | ✅（样片正式视频除外） | 提示词。Seedance 2.0 系列与 Seedance 2.5 建议中文不超过 500 字、英文不超过 1000 词（与官方建议一致，过长时模型可能忽略细节），`MiniMax-H3` ≤**2000** 字符（本平台当前入口限制，非官方上限）。**不要在提示词里写** `--dur` / `--rs` / `--rt` 这类内联参数——本原生入口**对所有模型都会直接拒绝**（`prompt_reserved_params`）。请一律使用请求字段；只有方舟兼容入口会解析内联参数（解析后从提示词中剥离） |
| `duration` | integer |  | 秒。不传时：`doubao-seedance-2.5` 默认 **-1**（与火山方舟官方一致）；`doubao-seedance-2.0`、`doubao-seedance-2.0-fast`、`MiniMax-H3` 默认 **5**。`doubao-seedance-2.0` / `doubao-seedance-2.0-fast` 为 **4–15 或 -1**，`doubao-seedance-2.5` 为 **4–30 或 -1**，`MiniMax-H3` 为 4–15（不能传 -1）。**-1＝由模型自动选择时长**（与火山方舟官方一致）：提交时按该模型最长时长预扣（Seedance 2.0 系列 15 秒、Seedance 2.5 为 30 秒），完成后按实际出片时长结算，多扣的部分退回；实际时长见查询结果 `metadata.duration`。`doubao-seedance-2.5` 视频编辑（`omni_reference_task_type: "edit"`）只接受 -1，不传即按 -1。越界会在提交时返回 400 |
| `resolution` | string |  | Seedance 系列：`480p` / `720p` / `1080p`，默认 **`720p`**，`doubao-seedance-2.0-fast` 最高 `720p`；**`4k` 只有 `doubao-seedance-2.0`**（按官方 4k 单价计费）；样片（`draft: true`）只能 `480p`、基于样片的正式视频只能 `1080p`（不传即自动取该档）；`MiniMax-H3`：`768p` / `2k`（传值小写，无 1080p），默认 **`768p`** |
| `aspect_ratio` | string |  | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`。`doubao-seedance-2.5` 带参考图时默认按参考生视频处理，画幅按你传的值生效；在首帧 / 首尾帧模式下输出画幅跟随首帧图，声明为视频编辑 / 视频延长（`omni_reference_task_type` 为 `edit` / `extend`）时跟随原视频，这些模式下传入的画幅不生效，也不会报错。`doubao-seedance-2.0` 系列在这些模式下可以指定画幅。注意：带参考视频但未声明子任务时，模型可能自行判定为编辑 / 延长，官方建议此时画幅传 `adaptive` |
| `image_urls` | array |  | 参考图，**最多 9 项；`doubao-seedance-2.5` 最多 30 项**；两种写法见下 |
| `video_urls` | string[] |  | 参考视频，最多 3 项（`doubao-seedance-2.5` 最多 10 项）；每项是公网视频链接，或 `asset://<视频素材ID>`（素材必须是 `kind: video`；把图片素材写在这里会被拒）。**Seedance 2.0 系列每段 2–15 秒、总时长 ≤15 秒；`doubao-seedance-2.5` 每段 2–30 秒（视频编辑 4–30 秒）、总时长 ≤30 秒**。超出时长范围会被拒绝，不扣费（错误码 `reference_video_duration_out_of_range` / `reference_video_total_too_long`）。链接须能直接下载（mp4 / mov）。**带参考视频的任务生成耗时显著增加**，轮询超时请相应放宽 |
| `audio_urls` | string[] |  | 参考音频，最多 3 项（`doubao-seedance-2.5` 最多 10 项、总时长 ≤30 秒）；每项是公网音频链接，或 `asset://<音频素材ID>`（素材必须是 `kind: audio`）；除 `doubao-seedance-2.5` 外**不能单独使用**，必须搭配参考图或参考视频 |
| `generate_audio` | boolean |  | 是否生成音轨。**不传默认 `true`（有声）**，与火山方舟官方默认一致；要无声显式传 `false`。建议两种情况都显式传，不依赖默认值 |
| `watermark` | boolean |  | 是否加水印 |
| `seed` | integer |  | `-1` ~ `4294967295`。官方只对 Seedance 1.0 列出该参数，对 Seedance 2.0 和 Seedance 2.5 **不生效（传了不报错）** |
| `camera_fixed` | boolean |  | 同上：官方只对 Seedance 1.0 列出，对 Seedance 2.0 和 Seedance 2.5 不生效（传了不报错） |
| `frames` | integer |  | 同上：官方只对 Seedance 1.0 列出，对 Seedance 2.0 和 Seedance 2.5 不生效（传了不报错）；请用 `duration` |
| `omni_reference_task_type` | string |  | 全模态参考的子任务：`auto` / `reference` / `edit`（视频编辑）/ `extend`（视频延长），`doubao-seedance-2.5` 官方参数（对 Seedance 2.0 系列不生效，传了不报错）。`edit` / `extend` 必须带至少一段 `video_urls`，否则 400；`edit` 的时长只能 -1；传其他值返回 400 |
| `return_last_frame` | boolean |  | 为 `true` 时，完成后查询结果带 `last_frame_url`（成片最后一帧的 JPEG，约 24 小时有效，本平台不转存），可作为下一段视频的首帧，拼接连续镜头。Seedance 2.0 和 Seedance 2.5 都支持；不另收费 |
| `draft` | boolean |  | 样片模式，仅 `doubao-seedance-2.5`：先生成一段 `480p` 预览确认镜头与动作，价格与普通 480p 相同。`doubao-seedance-2.0`、`doubao-seedance-2.0-fast`、`MiniMax-H3` 传 `true` 返回 400 |
| `draft_task_id` | string |  | 基于样片生成正式视频，仅 `doubao-seedance-2.5`：填你自己 7 天内、同一模型、已完成的样片任务号。正式视频固定 `1080p`，时长与样片相同，按普通 1080p 视频计费。**提示词、参考素材、时长、画幅、`seed`、`generate_audio`、`omni_reference_task_type` 由样片复用，不要再传**（传了返回 400） |
| `output_format` | string |  | `mp4`（默认）/ `mov`（仅 `doubao-seedance-2.5`，色彩精度更高，适合后期调色、抠像；部分播放器不兼容）。Seedance 2.0 系列只出 mp4：传 `mp4` 等于不传，传 `mov` 返回 400。不另收费 |
| `tools` | array |  | 联网搜索：`[{"type": "web_search"}]`，Seedance 2.0 和 Seedance 2.5 都支持。模型按提示词自行判断是否搜索，官方说明仅适用于纯文本输入；实际搜索次数见查询结果 `metadata.usage.tool_usage.web_search` |
| `priority` | integer |  | 排队优先级 `0`–`9`，数值越大越优先（默认 0），Seedance 2.0 和 Seedance 2.5 都支持 |
| `execution_expires_after` | integer |  | 任务过期秒数，`3600`–`259200`（默认 172800）。Seedance 2.0 和 Seedance 2.5 超时后最长等到这个时间再确认结果，见下方 `timeout` |
| `safety_identifier` | string |  | 你的终端用户标识（建议传哈希值），可打印 ASCII，≤64 字符，原样转给生成方（官方用途说明见火山方舟文档） |
| `service_tier` | string |  | Seedance 2.0 和 Seedance 2.5 只有在线推理：传 `default` 等于不传，传 `flex` 返回 400 |
| `generation_type` | string |  | `omni_reference`（多模态参考，默认语义）/ `first_and_last_frames`（首尾帧；此模式下参考视频和参考音频会被忽略） |
| `callback_url` / `callback_secret` | — | ❌ | **不支持，传了会报错**。请轮询 `poll_url` |

`image_urls` 每项可以是：

- **字符串**：一个公网图片链接，或 `asset://<素材ID>`。**只传 1 张**且不写 `role` 时按**首帧图生视频**处理。
- 🔴 **传 2 张及以上时（非首尾帧模式），没写 `role` 的图片按参考图（`reference_image`）处理**，你自己写了 `role` 的按你写的处理。适用 Seedance 2.0 和 Seedance 2.5。
- 单图**例外**：`doubao-seedance-2.5` 在非首尾帧模式下只传 1 张也按参考图处理（参考生视频）。
- 没写 `role` 的单图**同时带参考视频或参考音频**时，这张图按参考图处理。
- **对象**：`{ "url": "...", "role": "reference_image" }`，`role` 可选 `first_frame` / `last_frame` / `reference_image`。做多模态参考请显式写 `reference_image`

**`video_urls` / `audio_urls` 只传纯 URL 字符串**，不需要写 `role`（走方舟格式入口时，照官方示例在 `video_url` / `audio_url` 项上写这两个固定 role 也可以）。三个字段都可以用 `asset://` 素材引用，素材类型要与字段对应（图片→`image_urls`、视频→`video_urls`、音频→`audio_urls`）。

**请求头 `Idempotency-Key`**（可选但强烈建议）：网络重试时带同一把键，不会重复下单、不会重复扣费。**同一把键再提交一次，无论请求体是否改过，都返回首次创建的任务**，不校验请求体差异。新任务必须使用新键。

**成功响应**：

**响应示例 · 提交成功**

```
{ "job_id": "...", "status": "queued", "poll_url": "https://iwkey.com/videos/v1/videos/jobs/<job_id>",
  "created_at": "2026-08-21T..." }
```

5.2 提交前估价 · `POST /videos/v1/videos/generations/estimate`

请求字段与 5.1 完全相同。**不建任务、不扣费、不触发生成。**

| 响应字段 | 说明 |
| --- | --- |
| `model` | 估价对应的模型（回显） |
| `estimated_cost` | 预计费用（美元） |
| `estimated_cost_cny` | 折算人民币（仅展示参考） |
| `fx_cny_per_usd` | 展示汇率 |
| `currency` | `USD`（计费本位为美元） |
| `basis` | 估价口径，固定 `pre_hold`（按提交前的预扣口径估算） |
| `final_cost_may_adjust` | `true`——实际结算可能微调 |

5.3 查询任务 · `GET /videos/v1/videos/jobs/{job_id}`

| 字段 | 说明 |
| --- | --- |
| `status` | 见下方状态表 |
| `status_note` | 仅在需要说明时出现（中文一句话） |
| `video_url` | **生成引擎官方直链**；有效期不同模型所在的上游通道不同（多数约 24 小时），**以下面 `expires_at` 为准** |
| `expires_at` | 上面那条链接的到期时间 |
| `platform_video_url` | 本平台副本；**默认为 `null`**（未开通 7 天副本时不产生） |
| `platform_expires_at` | 副本到期时间（仅开通 7 天副本后返回） |
| `last_frame_url` / `last_frame_expires_at` | 尾帧图链接与到期时间（创建时 `return_last_frame: true` 才有，约 24 小时有效，本平台不转存）；否则为 `null` |
| `error` | 失败时的 `{code, message, details}`；**处理中恒为 `null`** |
| `cost_pending` / `cost_final` | 预扣 / 结算金额（美元） |
| `duration_ms` | 从提交到完成的耗时 |
| `metadata` | `duration`（实际时长，传 -1 时看这里）/ `resolution` / `ratio` / `seed` / `usage`（含联网搜索次数 `tool_usage`）/ `output_format` / `tools` 等 |

**任务状态**：

| 值 | 含义 |
| --- | --- |
| `queued` | 已受理，排队中 |
| `running` | 生成中 |
| `completed` | 已完成，可取片 |
| `failed` | 失败（预扣自动退回） |
| `cancelled` | 已取消 |
| `timeout` | 超时（预扣自动退回）。⚠️ 超时的任务仍可能出片：结果确认前状态保持 `running`，一般不超过 24 小时，Seedance 2.0 和 Seedance 2.5 最长等到该任务的 `execution_expires_after`（默认 48 小时，与官方一致），确认未出片才退款；原生入口此时会在响应里多一个 `status_note` 字段说明情况，方舟入口没有该字段。请把客户端总超时设到 48 小时以上（传了 `execution_expires_after` 的，按它来） |

⚠️ 看到 `running` 且带 `status_note` 时，表示结果仍在确认中，**此时费用尚未结算，请勿重复提交**。

5.4 任务列表 · `GET /videos/v1/videos/jobs`

| 参数 | 说明 |
| --- | --- |
| `page` / `page_size` | 页码（≥1）/ 每页条数（1–200，默认 20） |
| `status` | 按状态过滤，取值同上表 |
| `start_date` / `end_date` | `YYYY-MM-DD`，**均含当天** |
| `api_key_id` | 按密钥过滤 |

响应 `{ items: [...], total, page, page_size, fx_cny_per_usd }`，按提交时间倒序（不可调整）。`fx_cny_per_usd` 是本平台当前展示用的美元兑人民币汇率，仅供换算显示，扣费以美元为准。

5.5 消费统计 · `GET /videos/v1/videos/jobs/stats`

过滤参数同 5.4。返回 `total_jobs` / `completed_jobs` / `failed_jobs` / `in_flight_jobs` / `total_cost`（仅计已完成）/ `avg_duration_ms` / `fx_cny_per_usd`（展示用汇率，同 5.4）。

5.6 导出 · `GET /videos/v1/videos/jobs/export.csv`

过滤参数同 5.4。⚠️ **单次最多导出 200 行**，需要更多请用 5.4 分页自行汇总。

表头（列名与 5.3 任务对象字段一一对应）：`job_id, status, model, token_name, cost_final, cost_pending, duration_ms, created_at, completed_at, video_url, platform_video_url, error_code, error_detail, cost_final_cny (display only: cost_final x fx_cny_per_usd, converted at the current display FX), fx_cny_per_usd`。

5.7 素材库

**建素材** `POST /videos/v1/videos/assets`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | ✅ | http(s) 图片、视频或音频链接（带签名参数的临时链接可直接用） |
| `kind` | string |  | `image`（默认）/ `video` / `audio`（音频：wav / mp3，2–30 秒，≤15MB）。链接后缀与类型明显不符会被拒（`asset_kind_url_mismatch`） |
| `name` | string |  | ≤64 字符；**不能叫「图片」或「图片N」**（保留给位置语法）；同一账号内不可重名 |

响应含 `id`（查询与删除用）、`ref`（形如 `asset://xxx`，直接放进 `image_urls`）、`status`（`Processing` / `Active` / `Failed`）。**只有 `Active` 才能用于生成**（例外：`MiniMax-H3` 登记后即可引用，不看这个状态）。

**列出素材** `GET /videos/v1/videos/assets`
返回 `{ assets: [...] }`。
🔴 **这个接口用于管理素材，不要用它轮询状态**——轮询请用下面的「查单个素材」。

**查单个素材** `GET /videos/v1/videos/assets/<id>`
只返回你名下的这一张，字段与列表单条相同（`id`、`status` 等）；`<id>` 用建素材响应里的 `id` 或 `asset_id` 均可。不属于你的、不存在的、已删除的一律 404。登记后请用它按 id 轮询（每 2～3 秒），查到 `status` 为 `Active` 即可提交生成；`Failed` 时看 `error.code`：`asset_processing_timeout` 删掉后重新登记，`asset_processing_failed` 删掉后重新登记、再次失败就换一份文件（同名素材在删除前会被拒）。不必取回整个列表。
（可选）在多个模型之间来回切换时，可加 `?model=<模型名>` 让 `usable` 给出 true/false（不带或填了未知模型名时为 `null`）。

**删除素材** `DELETE /videos/v1/videos/assets/<素材ID>`
从你的库中移除。响应里的 `already_retired` 为 `true` 表示此前已删除（重复调用安全）。

**查询能力** `GET /videos/v1/videos/assets/capability?model=<模型名>`
返回 `enabled`（该模型能否用素材库）、`upload_max_bytes`、`upload_max_pixels`。**建议接入时读取一次该接口，不要把上限固定写在你的代码里。**

5.8 上传接口（视频工作台专用，API 接入通常不需要）

本平台提供一个图片上传接口，把本地文件转成可用的 URL。**API 接入通常不需要它**：直接提供公网 URL 即可（见「参考图」一节）。

`POST /videos/v1/videos/uploads`，请求体为图片原始字节（不是表单），用 `Content-Type` 声明类型（`image/jpeg` / `png` / `webp` / `gif` / `heic` / `heif` / `bmp` / `tiff`）；响应含 `url`。**只收图片：视频素材与参考视频没有上传接口**——视频一律提供公网可直接下载的链接（mp4 / mov），视频工作台里也是粘贴链接，不提供本地上传。

5.9 方舟兼容入口：与方舟原生的差异

已在用火山方舟原生格式的可直接接入 `POST /videos/api/v3/contents/generations/tasks`。下表只列不同之处：

| 项目 | 方舟原生 | 本平台 |
| --- | --- | --- |
| 地址与鉴权 | `https://ark.cn-beijing.volces.com/api/v3`，方舟 API Key | `base_url` 填 `https://iwkey.com/videos/api/v3`，`api_key` 填本平台 API Key；漏写 `/api/v3` 返回 404 |
| 模型名 | 模型 ID，或推理接入点 ID（`ep-` 开头） | 填模型名，如 `doubao-seedance-2-0-260128`；`ep-` 接入点 ID 返回 400 |
| 任务号 | 火山方舟任务 ID | 本平台 UUID |
| 回调 | 支持 `callback_url` | 不支持，传了返回 400，请轮询 `GET …/tasks/{id}` |
| 任务列表 | 只返回最近 7 天；`filter.model` 填推理接入点 ID | 含 7 天以前的任务；`filter.model` 填模型名 |
| 取消进行中的任务 | 排队中可取消，生成中不可取消 | 已交给生成方的，供应通道支持且生成方接受时可取消（预扣全额退回），否则返回 400；本平台排队中的也返回 400；409（`CancellationPending`）＝已取消、结算写入中，稍后查询。已结束任务的删除同官方，账单明细保留 |
| 错误码 | 方舟错误码 | 同方舟错误码（报错与失败任务的 `error.code` 都是）；方舟没有对应含义的少数情况返回本平台码，见表下说明 |
| 成片链接 | `content.video_url`，24 小时有效 | `content.video_url` 为生成方直链，有效期见 `content.expires_at`；转存成功时另给 7 天平台副本 `content.platform_video_url` |
| 请求参数 | 按官方参数表 | 表外参数返回 400 并点名，不静默丢弃；官方支持但当前通道未接通的，提交前返回 400（`InvalidParameter.UnsupportedParameter`），不扣费 |
| 真人参考图 | 方舟侧素材的 `asset://` | 须先登记到本平台[素材库](https://iwkey.com/docs/video-model/#asset-library)，用这里返回的 `asset://` |

**方舟兼容入口的错误码**：本平台特有的情况按含义取方舟错误码——API Key 无效 `AuthenticationError`，账号停用 `InvalidAccountStatus`，IP 不在白名单 `AccessDenied`；余额不足 `AccountOverdueError`；模型名不存在 `InvalidEndpointOrModel.NotFound`；提交过快 `AccountRateLimitExceeded`，同时在跑的任务数已满 `InflightBatchsizeExceeded`；生成方繁忙 `ServerOverloaded`；生成通道暂不可用 `NoAvailableService`；超时 `RequestTimeout`。参数不合法通常返回 `InvalidParameter`，具体情况也可能是 `MissingParameter`、`InvalidParameter.TaskTypeConstraint`、`InvalidParameter.TaskTypeMismatch`、`InvalidImageURL.EmptyURL` 或 `InvalidImageURL.InvalidFormat`；官方支持但当前通道未接通的参数返回 `InvalidParameter.UnsupportedParameter`。其他服务端错误通常返回 `InternalServiceError`，也可能是 `ServiceConnectionRefused`、`ContentSecurityDetectionError`。内容审核拦截通常返回 `Input…SensitiveContentDetected` / `Output…SensitiveContentDetected` 系列（`.PolicyViolation` 为版权，`.PrivacyInformation` 为疑似真人），也可能是 `InputTextRiskDetection` / `InputImageRiskDetection`；提交时的内容安全拦截（有随机性，重试一次通常能过）返回 `InvalidParameter`，原因见 `message`。以下情况方舟没有对应含义，返回本平台码，含义与处理见 [§06 错误码](https://iwkey.com/docs/video-model/#error-codes)：`task_not_found`、`inline_param_conflict`、`request_too_large`、`job_state_conflict`、`billing_in_progress`、`billing_reconcile_required`、`submission_result_ambiguous`、`upstream_state_persistence_failed`，以及无法确定被拦下的是文本、图片、视频还是音频时的 `input_content_sensitive` / `input_content_policy`；取消已受理、结算中为 `CancellationPending`（见上表「取消进行中的任务」）。

其余请求格式、报错格式、状态枚举、参数语义与官方一致；各参数对哪个模型生效见 5.1。提示词内联参数（`--rs` / `--dur` 等）会解析成对应字段，与顶层字段不一致时返回 400；基于样片生成正式视频时，`draft_task.id` 填本平台的样片任务号。

## 06 错误码

**请按 `code` 分支，不要匹配 `message` 文字。**上游给了原因时，`details.upstream_message` 会附上上游原话（已过滤掉链接、编号等内部信息，可能没有）；方舟兼容入口没有 `details`，这句原话拼在 `message` 末尾。

6.1 业务与参数类错误码

| code | HTTP | 含义 | 建议处理 |
| --- | --- | --- | --- |
| `input_image_real_person` | 400 | 参考图疑似含真人形象（参考视频含真人见 `input_content_sensitive`） | 这张图需要先加入素材库再使用 |
| `input_image_too_large` | 400 | 图片像素超上限 | 换小一点的图（`details` 里有实际尺寸与上限） |
| `output_content_policy` | 400 | 生成结果被上游内容审核拦下；`details.reason` 为 `copyright`（版权）或 `sensitive`（敏感信息），`details.media` 为 `video` 或 `audio`（`reason`、`media` 按上游给出的信息返回，可能没有） | 调整提示词或参考素材后重试 |
| `input_content_sensitive` | 400 | 你提交的内容被上游内容审核拦下；`details.reason` 为 `sensitive`（敏感内容）或 `real_person`（疑似含真人），`details.media` 指明是 `text` / `image` / `video` / `audio` 哪一类（`reason`、`media` 按上游给出的信息返回，可能没有） | 换掉被拦的内容后重试；`real_person` 且 `media` 为 `video` 时，先把视频登记到素材库再引用；为 `image` 时先把图片登记到素材库再引用 |
| `input_invalid_characters` | 400 | 提示词里有太多不可见或非法字符 | 清理提示词后重试 |
| `upstream_busy` | 503 | 上游现在比较忙 | 稍后重试 |
| `input_content_policy` | 400 | 你提供的参考素材或提示词被上游的版权检查拦下（拦的是输入，不是生成结果；若有 `details.media`，会指明是哪一种） | 换掉涉及版权的内容后重试 |
| `upstream_invalid_parameter` | 400 | 上游判定有参数不合法；若有具体提示，会写在 `details.upstream_message` | 有提示就按提示改参数后重试；没有提示就对照模型文档核对参数后重试 |
| `asset_processing_timeout` | 200 | 出现在素材对象的 `error.code`（查询素材照常返回 200；登记时被直接拒绝则以 400 返回）：上游处理这份素材超时 | 删掉这份素材后重新登记（同名素材在删除前会被拒） |
| `asset_processing_failed` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：上游内部错误或原因不明 | 删掉这份素材后重新登记；再次失败就换一份文件 |
| `asset_content_rejected` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：素材没通过上游内容审核；`error.details.reason` 为 `sensitive` / `copyright` / `real_person` / `face_mismatch` | 换一份文件重新登记；`face_mismatch` 请上传授权本人的素材 |
| `asset_format_unsupported` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：上游读不了这份文件；`error.details.reason` 为 `format` / `undetectable` / `transcoding` / `fps` | 转成支持的格式后重新登记（图片 jpeg / png / webp / bmp / tiff / gif / heic / heif，视频 mp4 / mov，音频 wav / mp3；视频帧率 24–60） |
| `asset_kind_mismatch` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：文件与声明的素材种类 `kind` 不一致 | 选对 `kind` 后重新登记 |
| `asset_audio_track_invalid` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：音轨不符合要求；`error.details.reason` 为 `required`（需要音轨）或 `forbidden`（不能带音轨） | 加上或去掉音轨后重新登记 |
| `asset_size_out_of_range` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：尺寸、比例、大小或时长超出上游允许的范围；`error.details.reason` 为 `too_small` / `too_large` / `aspect_ratio` / `file_size` / `pixel_count` / `duration` | 调整后重新登记：`file_size` 为文件太大，请压缩；`pixel_count`、`duration`、`aspect_ratio` 的方向不固定（过大或过小都可能），请对照所用模型对素材的要求，有 `details.upstream_message` 时按它调整 |
| `asset_download_failed` | 200 | 出现在素材对象的 `error.code`（查询返回 200；登记时被直接拒绝则以 400 返回）：上游下载不了这个链接 | 换成公网可直接访问的链接后重新登记 |
| `content_safety_rejected` | 400 | 提交内容未通过上游内容安全审核（审的是提示词与参考素材；**任务会以 `failed` 收场，预扣自动退回**） | 检查提示词与参考素材后，**换一个新的 Idempotency-Key** 重试（用旧键只会返回那单失败的任务） |
| `reference_media_unfetchable` | 400 | 参考图/视频读不到 | 检查链接是否公网可访问、是否太慢 |
| `invalid_asset_reference_format` | 400 | **素材引用的写法不对**（不是 `asset://<素材ID>` 的形态） | 请求方参数错误，须为 `asset://<素材ID>` 格式 |
| `invalid_asset_reference` | 400 | 引用的素材不在你的库里，或这个模型用不了它 | 换一个能用它的模型，或重新建素材 |
| `asset_unavailable` | 400 | 素材还不能用：还在处理中，或已处理失败 | `Processing` 等到 `Active` 再提交；`Failed` 查询该素材，按它的 `error.code` 处理 |
| `asset_library_full` | 400 | 素材数量已达上限（**仅在本平台为你的账号配置了素材数量上限时才会出现**；默认不限） | 删除不用的素材 |
| `unsupported_resolution` | 400 | 该模型不支持这个分辨率（例如 `doubao-seedance-2.5` 或极速档传了 `4k`、极速档传了 `1080p`、样片传了 `480p` 以外的档位） | 改用该模型支持的分辨率，见上方模型表 |
| `unsupported_parameter` | 400 | 该模型不支持这个参数 / 取值（例如 `doubao-seedance-2.0` 传 `draft: true` 或 `output_format: "mov"`；原生入口写了方舟入口的字段名 `ratio` / `content`；样片正式视频又传了提示词或时长），`message` 会点名字段 | 按 `message` 去掉或改正该字段 |
| `invalid_draft_task` | 400 | `draft_task_id` 用不了：不是你的任务、不是样片、还没完成、超过 7 天，或模型不同 | 重新生成样片后用新的任务号 |
| `frame_role_conflict` | 400 | 首帧/尾帧角色不能和参考视频同时用 | 去掉其中一类，不要混用 |
| `asset_kind_invalid` | 400 | 建素材时 `kind` 不是 `image` / `video` / `audio` | 改成这三个值之一 |
| `asset_kind_url_mismatch` | 400 | 建素材时链接后缀与 `kind` 明显不符（如 .mp4 配 image） | 改 `kind` 或换链接 |
| `asset_kind_field_mismatch` | 400 | 生成请求里素材类型与字段不符（如图片素材写进 `video_urls`、视频素材写进 `image_urls`、音频素材写进非 `audio_urls` 字段） | 图片素材放 `image_urls`，视频素材放 `video_urls`，音频素材放 `audio_urls` |
| `asset_kind_unsupported` | 400 | 该模型的素材库不支持这种素材类型 | 改传公网直链 |
| `asset_url_invalid` | 400 | 建素材的 `url` 不是 http(s) 链接 | 检查链接 |
| `invalid_inline_media` | 400 | Base64 内联素材格式不对（`data:` 前缀、MIME 类型、编码或文件格式不符合要求）；提交前校验，**不扣费** | 按 `message` 修正 Base64 内容，或改传公网链接 |
| `invalid_upload` | 400 | 上传文件不合规（超出大小限制或不是支持的类型） | 按上传接口的限制重传 |
| `unsupported_model` | 400 | 这个入口不支持该模型 | 换模型或换入口 |
| `idempotency_key_reused` | 409 | 同一个 `Idempotency-Key` 被用于内容不同的请求。**本页的原生入口与方舟兼容入口不会返回此码**：同一把键再提交会返回首次创建的任务，见 5.1 的说明 | 换一个新的 Idempotency-Key |
| `billing_in_progress` / <br>`billing_reconcile_required` | 409 | 这一单的扣费正在进行中（或已被挂起等待人工核对） | 🔴 **不要换新的 Idempotency-Key**：该键对应的扣费正在进行，换键会再扣一次。请**继续轮询该任务**；超过一分钟仍返回此码，请联系我们 |
| `job_state_conflict` | 409 | 请求没问题，但它指向的任务在这期间状态变了 | 先查询那个 `job_id`，等它到终态（completed / failed / timeout / cancelled）再**换一个新的 Idempotency-Key** 提交；**它可能仍占着预扣**，没等终态就重发会冻两份钱 |
| `storage_unavailable` | 503 | 平台存储暂时不可用 | 稍后重试。⚠️ 若发生在提交阶段，任务可能已创建并保留预扣、等待核对：请用**同一把** Idempotency-Key 重试，会回放原单；换新键可能冻两份钱 |
| `prompt_reserved_params` | 400 | 提示词里写了 `--dur` / `--rs` 等内联参数（本原生入口不解析） | 改用 `duration` / `resolution` 等请求字段 |
| `inline_param_conflict` | 400 | 仅方舟兼容入口：提示词内联参数与顶层字段的值不一致 | 二选一，去掉其中一处 |
| `audio_requires_visual` | 400 | 参考音频不能单独使用 | 补一张参考图或一段参考视频 |
| `invalid_request` | 400 | 参数不合法的通用码（类型不对、枚举值不在允许范围、超上限、**时长越界**等），`message` 会点名字段并给出允许范围。所有模型的时长越界都是这个码，没有单独的时长错误码 | 按 `message` 提示修正请求参数 |
| `too_many_reference_items` | 400 | 仅 `MiniMax-H3`：超出它特有的素材组合上限（如首/尾帧图数量）。其余情况下参考素材超过该模型上限（见「配额与限制」）返回 `invalid_request` | 减少参考图 / 参考视频数量 |
| `frame_and_reference_mixed` | 400 | 首/尾帧图与参考图混用（`MiniMax-H3` 等） | 二选一 |
| `reference_video_duration_out_of_range` | 400 | 参考视频单段时长超出范围（Seedance 2.0 系列 2–15 秒；`doubao-seedance-2.5` 2–30 秒，视频编辑 4–30 秒） | 裁剪后重新提交 |
| `reference_video_total_too_long` | 400 | 参考视频总时长超上限（Seedance 2.0 系列 15 秒；`doubao-seedance-2.5` 30 秒） | 少放一段或裁短一些 |
| `reference_video_duration_unverifiable` | 400 | 读不出参考视频的时长（链接不是可直接下载的 MP4 / MOV，如网盘分享页、需要登录的链接） | 换一个能直接下载的公网链接 |
| `asset_name_too_long` / `asset_name_reserved` / `asset_name_taken` | 400 | 注册素材时名字过长 / 用了保留格式「图片」「图片N」/ 与库里已有素材重名 | 换一个名字——名字就是提示词里的 @ 句柄，必须唯一且不能被截断 |
| `upload_expired` | 409 | 通过上传接口传的图片已过保留期，不能再入库 | 重新上传后再入库 |

6.2 鉴权与服务端错误码

| code | HTTP | 含义 | 建议动作 |
| --- | --- | --- | --- |
| `invalid_api_key` | 401/403 | 密钥无效或账号被禁用 | 检查配置，联系我们 |
| `ip_not_allowed` | 403 | 密钥绑定了网段，当前来源不在其中 | 联系我们调整 |
| `insufficient_credits` | 402 | 账户余额不足 | 充值；**建议自建余额预警** |
| `model_not_found` | 404 | 模型名不存在或未开通 | 检查模型名 |
| `task_not_found` | 404 | 任务不存在或不属于你 | 检查任务号 |
| `upload_quota_exceeded` | 429 | 上传配额触顶（**仅在本平台为上传接口启用了配额拦截时才会出现**；未启用时超额只记录不拦截） | **API 接入请直接提供公网链接，见「参考图」** |
| `rate_limit_exceeded` | 429 | 请求过于频繁 | 退避后重试 |
| `submission_rate_limited` | 429 | 本账号同时在跑的任务数、或最近一分钟的提交数触顶（**不是失败，任务没有被创建、也没有扣费**）；**该闸可能被本平台关闭，关闭时不会返回此码** | 按响应头 `Retry-After` 退避后重试；`details` 里带当前值与上限（`inflight`/`max_inflight` 或 `submits_last_minute`/`max_per_minute`），可据此自适应降速 |
| `upstream_timeout` | 504 | 生成超时（**预扣自动退回**） | 可重试 |
| `upstream_generation_failed` | 502/503 | 生成方侧失败（**预扣自动退回**）；建素材时素材库暂不可用也返回此码（此时不计费） | 退避后重试 |
| `submission_result_ambiguous` | 502 | 提交结果无法确认 | 🔴 **先联系我们，不要直接重试** |
| `internal_error` | 500 | 本平台内部错误 | 联系我们 |
| `billing_error` | 500 | 提交前的余额核验失败（计费系统暂时不可用）；发生在预扣**之前**，**未扣费** | 稍后重试；持续失败请联系我们 |
| `invalid_json` | 400 | 请求体不是合法 JSON | 检查序列化与 `Content-Type: application/json` |
| `request_too_large` | 413 | 请求体超过 64 MB（见「配额与限制」）；解析前拒绝，**不扣费** | 缩小请求体（大文件改传链接，或先转存 / 入素材库） |
| `not_found` | 404 | 路径不存在（method/URL 拼写或版本前缀有误，与业务层的 `task_not_found` / `model_not_found` 无关） | 核对请求地址（含 `base_url` 拼接，见 5.9「方舟兼容入口」差异表） |
| `asset_upstream_missing` | 502 | 素材暂时不可用，平台正在自动恢复 | 稍后重试 |
| `credits_lock_unavailable` | 503 | 系统繁忙，本次未扣费 | 稍后重试 |
| `discount_lookup_unavailable` | 503 | 暂时无法计价，本次未扣费 | 稍后重试 |
| `upstream_state_persistence_failed` | 503 | 任务可能已开始生成，但平台暂时无法记录它的状态 | 🔴 **先联系我们再重试**，盲目重试可能重复出片 |
| `upstream_channel_unavailable` | 502 | 生成服务暂时不可用（**与你的密钥无关**） | 退避后重试；持续不恢复请联系我们 |
| `missing_task_id` | 502 | 提交未成功，预扣自动退回 | 稍后重试 |

6.3 重试建议

- **400 类**：不要自动重试，请求本身要改。
- **401 / 402 / 404**：不要自动重试。
- **429**：指数退避。
- **502 / 503 / 504**：可退避重试，**但 `submission_result_ambiguous` 例外**——它表示我们无法确认那一单是否已在生成方受理，盲目重试可能重复出片重复计费。

## 07 归属与隔离边界 🔴 接入前必读

**素材与任务的归属，按你的账号划分，不按密钥划分。**

这一节在什么情况下与你有关

如果你只在自己的服务内部调用本接口、由你决定谁能看到什么，那么下面这些不会影响到你的使用者——他们看到的一切，都由你的产品决定。但如果你打算把**素材的列表、查询或删除能力**转交出去（例如给使用者开一个素材管理面板，或把本接口的密钥直接发给他们），请先读完这一节。

本平台以主账号为隔离边界：同一账号下签发的所有密钥，在平台看来属于同一个主体。于是：

- 一旦你把「列出素材」「删除素材」这两个能力透传出去，使用者 A 就**能看到、并且能删除**使用者 B 上传的素材
- 素材库是**账号级**的，你名下全体使用者共用同一个素材库
- 消耗明细我们最细只能提供到密钥这一级

使用者不直接调用本接口，隔离须由你实现

本平台只能识别到**你的账号**这一层，看不到、也无法区分你的产品上具体是哪个使用者在操作。**使用者之间"谁能看到谁、谁有什么权限"，只能由你在自己的产品里实现**。

不同客户之间彼此隔离：**账号与账号互不可见，你看不到其他客户的素材**。

🔴 **合规须知：真人形象素材的授权由接入方负责。**本平台的素材库通道**不包含**生成引擎官方的实名认证 / 活体验证流程，也不产生任何「被拍摄者已授权」的凭证。

**你须自行确保**：你的产品上所有上传真人形象素材的使用者，对该形象拥有合法使用与授权，并**自行留存**相应的授权证明；你应在与你的使用者签订的服务协议中，就此作出相应约定。**涉及未成年人形象、声音等，须遵循更严格的合规要求。**

## 08 配额与限制

| 项 | 限制 | 作用域 |
| --- | --- | --- |
| 提示词长度 | Seedance 2.0 和 Seedance 2.5 建议中文不超过 500 字、英文不超过 1000 词；`MiniMax-H3` 2000 字符（本平台当前入口限制，非官方上限） | 每请求 |
| 参考图数量 | Seedance 2.0 系列与 `MiniMax-H3` 9 张；Seedance 2.5 30 张 | 每请求 |
| 参考视频 / 音频数量 | Seedance 2.0 系列与 `MiniMax-H3` 各 3 段（各自总时长 ≤15 秒）；Seedance 2.5 各 10 段（各自总时长 ≤30 秒） | 每请求 |
| 单张图片像素 | **3600 万**（宽×高，本平台上传预检值；对应现役供应通道生产实测的生成时上游限制，其他通道可能不同） | 每张 |
| 单张图片大小 | 30 MB | 每张 |
| 请求体总大小 | 64 MB（与官方一致；带 Base64 素材的大请求会排队依次处理） | 每请求 |
| CSV 单次导出 | 200 行 | 每请求 |

⚠️ **成片链接会过期**：默认仅提供生成引擎官方直链，**具体有效期以响应里的 `expires_at` 为准**（不同模型所在的上游通道不同，多数约 24 小时），请及时下载转存到你自己的存储；如需本平台保留 **7 天**副本，可联系我们开通。

⚠️ 取消任务在方舟兼容入口提供，适用于**当前供应通道支持取消**的进行中任务：取消成功则预扣全额退回；生成方不再接受取消、或当前通道不支持取消时返回 400；还在本平台排队、尚未提交给生成方的任务同样返回 400。已结束的任务可以删除记录（见 5.9「方舟兼容入口：与方舟原生的差异」）。失败、超时的任务会自动退回预扣。

## 09 常见接入问题

**为什么我传的图被拒了？**

三种常见原因——图里有真人形象（走素材库，见「素材库：真人形象的唯一通道」）；图片尺寸超上限（先压图，见「参考图」）；内容涉及版权或敏感信息。错误信息里会说明是哪一种。

**`@张三` 为什么不生效？**

接口上要写 `@图片1`，见「人物命名与位置语法」。

**我的用户之间素材互相可见，怎么办？**

见「归属与隔离边界」，需要你在自己那一层实现隔离。

**任务多久出片？**

耗时取决于模型、时长与画面复杂度。请异步轮询响应里的 `poll_url`，不要同步等待。

**可以取消任务吗？**

当前供应通道支持取消时可以。在方舟兼容入口对进行中的任务发 `DELETE …/tasks/{id}` 即申请取消，取消成功预扣全额退回；生成方不再接受取消、或当前通道不支持取消时返回 400；还在排队、尚未提交给生成方的任务同样返回 400。已结束的任务用同一个接口删除记录。失败、超时的任务会自动退回预扣。

**想了解更多接入细节？**请联系 support@iwkey.com，我们会尽快与你确认接入细节。