# 视频生成

> 用 Seedance、可灵或 MiniMax H3 生成视频：文生、首帧、首尾帧和多模态参考的输入方式，各模型的参数取值，以及提交、查询和完成后的完整响应。

<a id="media-videos-h-c80d5192"></a>

## 接口

| 项目 | 内容 |
| --- | --- |
| 方法与地址 | `POST https://platform.sgt.site/media/v1/videos/generations` |
| 请求头 | `Authorization: Bearer <虚拟密钥>`、`Content-Type: application/json`；建议加 `Idempotency-Key` |
| 返回 | 任务对象 `media.task`，通常是 HTTP 202、`status: "queued"` |
| 查询结果 | `GET https://platform.sgt.site/media/v1/tasks/{id}`，建议每 5 秒一次，直到 `succeeded` 或 `failed` |
| 结果位置 | `artifacts[]`：视频 `kind: "video"`，可能另有封面 `cover` 和尾帧 `last_frame` |
| 取消 | 仅 Seedance 支持，且只能在排队（`queued`）时取消 |

视频生成一般需要几十秒到数分钟。提交时用 `"wait": 0` 立即拿到任务 ID，再轮询；完整的轮询脚本见[快速开始](overview.md)。

<a id="media-videos-h-78fe371f"></a>

## 四种输入方式

所有素材都放在 `references` 数组中，用 `role` 和 `type` 区分用途：

| 输入方式 | `references` 怎么填 | 支持的模型 |
| --- | --- | --- |
| 文生视频 | 不传 `references`，只写 `prompt` | 全部 |
| 首帧生视频 | 1 项 `first_frame` / `image` | 全部 |
| 首尾帧生视频 | 1 项 `first_frame` / `image` + 1 项 `last_frame` / `image` | 除可灵 Turbo 外 |
| 多模态参考 | 若干 `reference` / `image`、`reference` / `video`、`voice` / `audio` | Seedance 全系列、MiniMax H3；可灵 Omni 只支持参考图和参考视频 |

每一项的写法：

```json
{"role": "first_frame", "type": "image", "url": "https://files.example.com/first.png"}
```

| 项目 | 规则 |
| --- | --- |
| 图片来源 | 每项只能填一种：`url`（公网 HTTP(S) 地址）、`file_id`（[上传文件](media-files.md)得到的 `id`）、`asset_id`（已审核素材，仅 Seedance 的 `reference` 与 `voice` 角色支持） |
| 单个文件大小 | 图片 10 MiB，视频 200 MiB，音频 15 MiB |
| 组合限制 | Seedance 和 MiniMax H3 中，首帧或首尾帧不能与多模态参考同时使用；所有模型的尾帧都必须搭配首帧 |

<a id="media-videos-h-745804a6"></a>

## 通用参数

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填。模型 ID，见[模型列表：视频模型与输入方式](models.md#models-media-videos) |
| `prompt` | string | 画面与镜头描述。可灵和 MiniMax H3 必填；Seedance 可省略，但此时必须提供参考素材 |
| `duration` | integer | 视频秒数，默认 5。取值见各模型 |
| `resolution` | string | 清晰度，取值见各模型。注意大小写 |
| `aspect_ratio` | string | 宽高比，取值见各模型 |
| `generate_audio` | boolean | 是否生成声音。Seedance 默认 `true`，可灵 3.0 与 Omni 默认 `false`；可灵 Turbo 和 MiniMax H3 不接受此字段 |
| `seed` | integer | 仅 Seedance：随机种子，-1 至 2147483647 |
| `references` | array | 首帧、尾帧或参考素材，见上文 |
| `provider_options` | object | 厂商选项，见各模型 |
| `metadata` | object | 你的业务信息，随任务原样返回；不超过 64 KiB |
| `callback_url` | string | 可选。接收任务状态通知的 HTTPS 地址；平台验签、重试和网络范围见[任务回调](task-callbacks.md) |
| `wait` | integer | 本次请求最多等待的秒数，0–50，默认 0。视频建议填 0 |

表中某模型不接受的字段，传入会返回 400 `unsupported_parameter`。不用的字段直接省略，不要传 `null`。

<a id="media-videos-h-42316219"></a>

## Seedance 参数怎么填

适用于 `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`、`doubao-seedance-2-0-mini-260615`、`doubao-seedance-2-5-260628`。

| 字段 | 2.0 | 2.0 Fast、2.0 Mini | 2.5 |
| --- | --- | --- | --- |
| `resolution` | `480p`、`720p`、`1080p`、`4k`，默认 `720p` | `480p`、`720p`，默认 `720p` | `480p`、`720p`、`1080p`，默认 `720p` |
| `duration` | `-1` 或 4–15，默认 5 | `-1` 或 4–15，默认 5 | `-1` 或 4–30，默认 5 |
| `aspect_ratio` | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`，默认 `16:9` | 同左，默认 `16:9` | 同左，默认 `adaptive` |
| `generate_audio` | 默认 `true` | 默认 `true` | 默认 `true` |
| 参考图 `reference` / `image` | 最多 9 张 | 最多 9 张 | 最多 30 张 |
| 参考视频 `reference` / `video` | 最多 3 段 | 最多 3 段 | 最多 10 段 |
| 参考音频 `voice` / `audio` | 最多 3 段，必须同时有参考图或参考视频 | 同左 | 最多 10 段，可单独使用 |

补充说明：

- `duration: -1` 由模型自行决定时长，按实际时长结算。
- `adaptive` 由模型根据输入素材决定宽高比。2.5 的首帧和首尾帧模式请使用 `adaptive`。
- `480p`、`720p` 是清晰度档位，实际像素由宽高比决定，不是固定的正方形尺寸。
- 不需要声音时显式传 `"generate_audio": false`。
- `provider_options.volcengine` 可用 `watermark`（布尔值，添加水印）和 `return_last_frame`（布尔值，额外返回最后一帧图片，便于续拍下一段）。
- 首帧和尾帧只接受 `url` 或 `file_id`，不接受 `asset_id`。

<a id="media-videos-h-6f0065e8"></a>

## Seedance 2.5：先预览样片，再生成正式视频

样片模式已接入 `doubao-seedance-2-5-260628`。两个阶段均调用本页的视频生成接口，并分别返回任务 ID、分别冻结和结算费用。平台不会在样片完成后自动生成正式视频。

第一步，显式使用 `480p` 和 `provider_options.volcengine.draft: true`，其他输入按该型号填写：

```bash
curl -s "$GATEWAY_ORIGIN/media/v1/videos/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sample-demo-001" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "一个蓝色杯子放在白色桌上，镜头缓慢拉远",
    "duration": 4,
    "resolution": "480p",
    "generate_audio": false,
    "provider_options": {"volcengine": {"draft": true}},
    "wait": 0
  }'
```

用响应 `id` 查询任务并预览视频。只有 `status: "succeeded"` 且确实通过样片模式创建的任务，才能用于第二步；普通 480p 视频不等于样片。

第二步，使用**同一消费身份、同一协议**的样片 ID，显式指定 `1080p`，换一个幂等键：

```bash
SAMPLE_TASK_ID="替换为已成功样片的平台任务 id"
curl -s "$GATEWAY_ORIGIN/media/v1/videos/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: final-demo-001" \
  -d "{\"model\":\"doubao-seedance-2-5-260628\",\"resolution\":\"1080p\",\"provider_options\":{\"volcengine\":{\"draft_task_id\":\"$SAMPLE_TASK_ID\",\"return_last_frame\":true}},\"wait\":0}"
```

| 参数或规则 | 说明 |
| --- | --- |
| `provider_options.volcengine.draft_task_id` | 成功样片的平台任务 ID，不接受厂商 ID，不接受其他协议的任务 ID |
| `draft` | 正式视频省略或设为 `false`；不能与 `draft_task_id` 同时设为 `true` |
| 继承输入 | 不再传 `prompt`、`references`、`duration`、`aspect_ratio`、`seed`、`generate_audio`，它们由厂商从样片继承；重传会返回 400 |
| 可独立指定 | `output_format`（`mp4`/`mov`）、`provider_options.volcengine.watermark`、`return_last_frame`；未指定按厂商默认值处理 |
| 有效期 | 从样片的厂商 `created_at` 起 7 天，独立于视频下载链接有效期；链接过期不代表样片引用必然过期 |
| 授权与上游身份 | 每次重新校验模型权限和原渠道身份；原 Key 被移除、停用或模型映射发生冲突时拒绝，不自动切换账号 |
| 删除保护 | 正式任务在提交中、运行中或结果待核对时阻止删除来源样片；确认终态并完成账务恢复后释放占用 |
| 原平台素材 | 正式提交前重新检查样片引用的素材仍存在、当前授权及原服务身份仍有效；不可用时在冻结费用和发送正式请求前拒绝 |
| 金额 | 按正式提交时的有效价格预留，沿用来源的可靠时长与输入事实估算；不复用样片旧价格，也不自动补扣旧账单 |

样片任务额外返回 `generation_stage: "draft"`；正式任务返回 `generation_stage: "final"` 和 `source_task_id`。其余响应与普通视频任务相同。每次显式提交正式视频都是独立生成；遇到 `reconciling` 请查询原任务，不要换幂等键重提。

**样片引用期限与继承素材的保留规则**

两个阶段之间不会延长平台素材原有的保留期。七天只是样片引用期限，原素材可能在此之前被清理或删除；官方没有承诺原素材对象删除后仍可生成正式视频。请在原素材仍有效时转换，正式请求仍须省略 `references`。平台会复核并占用继承素材，不把它们重新拼入正式请求；本次请求在途或结果未知期间拒绝删除这些素材，终态后不永久保留。缺少可靠素材来源记录的旧样片无法转换，平台不会从可能截断的输入展示中猜测来源。


<a id="media-videos-h-6f13df2e"></a>

## 可灵 Kling 参数怎么填

适用于 `kling-3.0`、`kling-3.0-turbo`、`kling-3.0-omni`。

| 字段 | 3.0 | 3.0 Turbo | 3.0 Omni |
| --- | --- | --- | --- |
| `prompt` | 必填，1–3072 字符 | 同左 | 同左 |
| `resolution` | `720p`、`1080p`、`4k`，默认 `720p` | `720p`、`1080p`，默认 `720p` | `720p`、`1080p`、`4k`，默认 `720p` |
| `duration` | 3–15，默认 5 | 3–15，默认 5 | 3–15，默认 5 |
| `aspect_ratio` | `16:9`、`9:16`、`1:1`，默认 `16:9` | 同左 | 同左 |
| `generate_audio` | 默认 `false` | 不接受 | 默认 `false` |
| 首帧 / 尾帧 | 各 1 张 | 仅首帧 1 张 | 各 1 张 |
| 参考图 / 参考视频 | 不支持 | 不支持 | 参考图最多 7 张，参考视频最多 1 段 |
| `provider_options.kling` | `watermark`、`multi_shot` | `watermark` | `watermark`、`multi_shot` |

补充说明：

- 素材来源为 `url` 或 `file_id`，不支持 `asset_id`。
- `multi_shot` 只在 Omni 带参考视频时为 `true`；其他情况（包括 3.0 的所有请求）如果传了必须为 `false`，一般直接省略。
- Omni 带参考视频时：参考图最多 4 张，`generate_audio` 不能为 `true`，参考视频最多 1 段。
- Omni 的提示词可以用 `<<<image_1>>>`、`<<<image_2>>>` 指代第几张图片，按 `references` 中图片项的顺序从 1 编号，序号不能超过图片数量。
- 可灵不支持 `seed` 和任务取消。

<a id="media-videos-h-18f9194f"></a>

## MiniMax H3 参数怎么填

适用于 `MiniMax-H3`。

| 字段 | 取值 |
| --- | --- |
| `prompt` | 必填，1–7000 字符 |
| `resolution` | `768P`、`2K`（大写），默认 `2K` |
| `duration` | 4–15，默认 5 |
| `aspect_ratio` | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。纯文生默认 `16:9`，且不能用 `adaptive`；带首帧或首尾帧时只能用 `adaptive`（可省略）；带参考素材时默认 `adaptive` |
| 首帧 / 尾帧 | 各 1 张 |
| 参考素材 | 参考图最多 9 张、参考视频最多 3 段、参考音频（`voice` / `audio`）最多 3 段 |
| `provider_options.minimax` | `watermark` |

补充说明：素材来源为 `url` 或 `file_id`，不支持 `asset_id`；帧模式和参考模式不能混用。H3 不接受 `generate_audio` 和 `seed`，不支持任务取消。费用按厂商回报的实际用量结算，用量证据缺失时生成可以成功而账务显示 `reconciling`，详见[任务查询与结算](media-tasks.md)。

<a id="media-videos-h-17d044b5"></a>

## 完整请求示例

以下示例可直接复制，先按[快速开始](overview.md)设置 `GATEWAY_ORIGIN` 和 `KEY`。每个新的生成请求请换一个新的 `Idempotency-Key`；把 JSON 保存为 `body.json` 后可用 `-d @body.json` 提交。

按使用场景选择示例。表中只列出支持该用法的型号；当前密钥能否使用，以[模型列表](models.md#models-media-videos)的查询结果为准：

| 我要做什么 | 支持的型号 | 示例 |
| --- | --- | --- |
| 只用文字生成 | 全部型号 | [文生视频（Seedance）](#media-videos-h-01b55631)、[可灵 3.0 文生视频](#media-videos-h-2c7d4440) |
| 用一张首帧图片生成 | 全部型号 | [首帧生视频](#media-videos-h-0e7e78e7)、[MiniMax H3 首帧生视频](#media-videos-h-6c7a5b94) |
| 指定首帧和尾帧 | Seedance 全部型号；`kling-3.0`、`kling-3.0-omni`；`MiniMax-H3`（`kling-3.0-turbo` 不支持） | [首尾帧生视频](#media-videos-h-ffac1f54) |
| 用参考图、参考视频或配音 | Seedance 全部型号；`kling-3.0-omni`（不支持音频）；`MiniMax-H3` | [多模态参考（Seedance）](#media-videos-h-261b1251)、[可灵 Omni 参考图与参考视频](#media-videos-h-a63623e7) |
| 先看 480p 样片，再生成正式视频 | 仅 `doubao-seedance-2-5-260628` | [Seedance 2.5 样片流程](#media-videos-h-6f0065e8) |
| 提交后可能需要取消 | 仅 Seedance，且任务仍在排队 | [取消任务](#media-videos-h-537d17f1) |

<a id="media-videos-h-01b55631"></a>

### 文生视频（Seedance）

```bash
curl -s "$GATEWAY_ORIGIN/media/v1/videos/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-demo-001" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "清晨的海边，镜头从沙滩缓慢推向远处的灯塔，海浪轻拍岸边",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "metadata": {"order_id": "V1001"},
    "wait": 0
  }'
```

<a id="media-videos-h-0e7e78e7"></a>

### 首帧生视频

```json
{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "画面中的人物转身微笑，镜头缓慢推近",
  "references": [
    {"role": "first_frame", "type": "image", "url": "https://files.example.com/first.png"}
  ],
  "duration": 5,
  "resolution": "720p",
  "generate_audio": false,
  "wait": 0
}
```

<a id="media-videos-h-ffac1f54"></a>

### 首尾帧生视频

```json
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "花苞逐渐绽放成盛开的花朵，延时摄影效果",
  "references": [
    {"role": "first_frame", "type": "image", "file_id": "替换为首帧的文件 id"},
    {"role": "last_frame", "type": "image", "file_id": "替换为尾帧的文件 id"}
  ],
  "duration": 6,
  "aspect_ratio": "adaptive",
  "wait": 0
}
```

<a id="media-videos-h-261b1251"></a>

### 多模态参考（Seedance）

用参考图确定人物形象，参考视频提供动作，参考音频提供配音，并要求返回尾帧：

```json
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考图中的人物按照参考视频的动作跳舞，口型与配音同步",
  "references": [
    {"role": "reference", "type": "image", "url": "https://files.example.com/person.png"},
    {"role": "reference", "type": "video", "url": "https://files.example.com/dance.mp4"},
    {"role": "voice", "type": "audio", "url": "https://files.example.com/voice.wav"}
  ],
  "duration": 8,
  "resolution": "720p",
  "provider_options": {"volcengine": {"return_last_frame": true}},
  "wait": 0
}
```

<a id="media-videos-h-2c7d4440"></a>

### 可灵 3.0 文生视频

```json
{
  "model": "kling-3.0",
  "prompt": "一只蓝色纸船在平静的水面上缓缓漂流，固定机位，白天",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "generate_audio": true,
  "wait": 0
}
```

<a id="media-videos-h-a63623e7"></a>

### 可灵 Omni 参考图与参考视频

```json
{
  "model": "kling-3.0-omni",
  "prompt": "<<<image_1>>> 中的角色在 <<<image_2>>> 的场景中，模仿参考视频的动作",
  "references": [
    {"role": "reference", "type": "image", "url": "https://files.example.com/character.png"},
    {"role": "reference", "type": "image", "url": "https://files.example.com/scene.png"},
    {"role": "reference", "type": "video", "url": "https://files.example.com/motion.mp4"}
  ],
  "duration": 5,
  "resolution": "720p",
  "provider_options": {"kling": {"multi_shot": true}},
  "wait": 0
}
```

<a id="media-videos-h-6c7a5b94"></a>

### MiniMax H3 首帧生视频

```json
{
  "model": "MiniMax-H3",
  "prompt": "镜头环绕画面中的跑车，车灯亮起",
  "references": [
    {"role": "first_frame", "type": "image", "url": "https://files.example.com/car.png"}
  ],
  "duration": 6,
  "resolution": "768P",
  "aspect_ratio": "adaptive",
  "wait": 0
}
```

<a id="media-videos-h-3b1f210d"></a>

## 响应

<a id="media-videos-h-985a38e0"></a>

### 提交成功（HTTP 202）

```json
{
  "id": "task_example",
  "object": "media.task",
  "model": "doubao-seedance-2-0-260128",
  "type": "video",
  "status": "queued",
  "progress": 0,
  "created_at": 1791763200,
  "started_at": null,
  "finished_at": null,
  "artifacts": [],
  "error": null,
  "billing": {"status": "reserved", "currency": "CNY", "amount": null},
  "metadata": {"order_id": "V1001"},
  "request_id": "req_example"
}
```

保存 `id`，用 `GET /media/v1/tasks/{id}` 查询。生成过程中 `status` 为 `running`；`progress` 只作参考，不同模型的更新粒度不同，以 `status` 判断是否完成。`billing.status: "reserved"` 表示已预留费用，完成后按实际用量结算。

<a id="media-videos-h-85c2916b"></a>

### 生成成功

下例为开启 `return_last_frame` 的 Seedance 任务，包含视频、封面和尾帧三个产物。ID、链接与金额均为示意：

```json
{
  "id": "task_example",
  "object": "media.task",
  "model": "doubao-seedance-2-0-260128",
  "type": "video",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1791763200,
  "started_at": null,
  "finished_at": 1791763290,
  "artifacts": [
    {"index": 0, "kind": "video", "mime_type": "video/mp4", "state": "available", "url": "https://example.com/result.mp4", "url_type": "upstream", "expires_at": null},
    {"index": 1, "kind": "cover", "mime_type": "image/jpeg", "state": "available", "url": "https://example.com/cover.jpg", "url_type": "upstream", "expires_at": null},
    {"index": 2, "kind": "last_frame", "mime_type": "image/png", "state": "available", "url": "https://example.com/last.png", "url_type": "upstream", "expires_at": null}
  ],
  "error": null,
  "billing": {"status": "settled", "currency": "CNY", "amount": "1.200000"},
  "metadata": {"order_id": "V1001"},
  "request_id": "req_example"
}
```

| 产物 `kind` | 内容 |
| --- | --- |
| `video` | 结果确有视频时返回；可为 MP4 或 MOV，不能由类别推断容器或编码 |
| `cover` | 视频封面图（有则返回） |
| `last_frame` | Seedance 请求 `return_last_frame=true` 且结果确含尾帧时出现；可作为下一段视频首帧，不保证每个任务都有 |

可灵和 MiniMax H3 通常只返回一个 `video` 产物。产物数量和顺序因模型而异，请按 `kind` 识别，不要按 `index` 写死。`url_type` 为 `upstream` 时是厂商的临时链接：Seedance 24 小时内有效（2.5 的视频链接最多下载 100 次），MiniMax H3 为限时链接，可灵产物 30 天后清理，请在完成后尽快下载或转存。下载时不要带 `Authorization`。其余字段含义见[图片生成的字段说明](media-images.md)和[任务查询与结算](media-tasks.md)。

<a id="media-videos-h-d2783568"></a>

### 下载视频、封面和尾帧

`kind`（string）区分用途；`url`（非空 string）与 `state=available` 才能用于下载。封面、尾帧字段未出现表示没有交付该项，不是空视频，也不据此猜一个 URL。`mime_type=video/mp4` 对应 `.mp4`，`video/quicktime` 对应 `.mov`；封面/尾帧按实际 JPEG/PNG 命名。签名路径不含可靠扩展名，未知 MIME/文件头保留 `.bin`。MP4/MOV 是容器，播放器还需支持其中的编码，不能靠改扩展名完成转换。

将[快速开始脚本](overview.md#overview-h-600de8a7)保存为 `media_client.py`，恢复已有任务并下载全部产物：

```bash
export TASK_ID="替换为视频任务 id"
python media_client.py
```

脚本检查空地址、HTTP 失败与未完整下载；暂不可读时继续查询原任务。签名过期可重新查询获取新授权，上游文件过期/下载次数耗尽不能靠重签恢复。客户端不能播放时先检查容器和编码，不重新生成；费用待核对时保留任务 ID。完整规则见[交付恢复](media-tasks.md)。

<a id="media-videos-h-470f92db"></a>

### 生成失败

```json
{
  "id": "task_example",
  "object": "media.task",
  "model": "doubao-seedance-2-0-260128",
  "type": "video",
  "status": "failed",
  "progress": 0,
  "created_at": 1791763200,
  "started_at": null,
  "finished_at": 1791763230,
  "artifacts": [],
  "error": {
    "code": "provider_rejected",
    "message": "厂商返回的失败原因（示意）",
    "stage": "generation",
    "retryable": false
  },
  "billing": {"status": "released", "currency": "CNY", "amount": null},
  "metadata": {"order_id": "V1001"},
  "request_id": "req_example"
}
```

`billing.status: "released"` 表示没有扣费，预留已释放。常见失败原因是提示词或素材未通过内容审核；修改后用新的 `Idempotency-Key` 重新提交。

<a id="media-videos-h-537d17f1"></a>

## 取消任务

仅 Seedance 支持，且只能取消仍在排队（`queued`）的任务：

```bash
curl -s -X POST "$GATEWAY_ORIGIN/media/v1/tasks/$TASK_ID/cancel" \
  -H "Authorization: Bearer $KEY"
```

成功时返回 HTTP 200 和任务对象，`status` 为 `cancelled`；对已取消的任务重复调用也返回 200。任务已开始生成时返回 400 `This task cannot be cancelled in its current state`；对可灵、MiniMax H3 调用返回 400 `This model does not support task cancellation`。取消后继续查询任务的 `billing`，确认费用已释放。

<a id="media-videos-h-5b17a229"></a>

## 常见错误

| 报错信息（`error.message`） | 原因 | 改法 |
| --- | --- | --- |
| Model type does not match the submission path | 把图片或 3D 模型提交到了视频地址 | 视频模型使用 `/media/v1/videos/generations` |
| prompt or references is required | Seedance 既没写提示词也没传素材 | 至少提供其中之一 |
| prompt is required | 可灵或 MiniMax H3 没写提示词 | 补充 `prompt` |
| duration has an unsupported value | Seedance 的时长不在 `-1` 或 4–15（2.5 为 4–30）内 | 改为允许的整数秒 |
| duration is outside the supported range | 可灵或 MiniMax H3 的时长超出范围 | 可灵 3–15，H3 4–15 |
| resolution has an unsupported value | 档位不在该模型支持范围，或大小写不对 | Seedance 与可灵用 `720p`、`4k`；H3 用 `768P`、`2K` |
| Parameter generate_audio is not supported by this model | 给可灵 Turbo 或 MiniMax H3 传了 `generate_audio` | 删除该字段 |
| Use one first frame, a first/last pair, or reference media; these modes cannot be combined | Seedance 混用了首尾帧与参考素材，或只有尾帧 | 二选一；尾帧必须搭配首帧 |
| This model requires reference images or video with voice audio | Seedance 2.0 系列只传了参考音频 | 同时提供参考图或参考视频 |
| last_frame requires first_frame | 可灵只传了尾帧 | 补充首帧 |
| Omni reference video permits at most four reference images and requires generate_audio=false | 可灵 Omni 带参考视频时参考图超过 4 张或开启了声音 | 减少参考图，去掉 `generate_audio: true` |
| multi_shot must be true with a reference video and false otherwise | `multi_shot` 与是否有参考视频不一致 | 有参考视频时传 `true`，否则传 `false` 或省略 |
| MiniMax frame inputs cannot be combined with reference media | H3 混用了首尾帧与参考素材 | 二选一 |
| MiniMax frame inputs require adaptive aspect_ratio | H3 带首帧时设置了固定比例 | 改为 `adaptive` 或省略 |
| MiniMax text-to-video cannot use adaptive aspect_ratio | H3 纯文生用了 `adaptive` | 改为固定比例或省略 |
| Too many references for role reference | 参考素材超过该模型上限 | 按上方表格减少 |
| Parameter references.role or references.type is not supported by this model | 该模型不支持这种素材，例如给可灵 3.0 传参考图、给可灵 Turbo 传尾帧 | 按“四种输入方式”表格换模型或改输入方式 |
| Parameter references.asset_id is not supported by this model | 在不支持的模型或角色上用了 `asset_id` | 改用 `url` 或 `file_id` |

完整错误码见[媒体错误处理](media-errors.md)。需要厂商原生请求格式时，见[Seedance 原生接口](native-seedance.md)、[可灵原生接口](native-kling.md)和[MiniMax H3 原生接口](native-h3.md)。