> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Doubao

> Doubao 视频生成参数、支持取值、输入限制与请求示例。

本页说明 `doubao-seedance-*` 视频路由。Doubao 是路由或产品前缀，Seedance 是视频模型系列；请使用完整模型 ID，不要自行替换前缀。

`POST https://api.mixroute.ai/v1/video/generations`

<Info>
  请求顶层保留 `model`、`prompt`、`asset`。所有厂商字段统一放入 `metadata`，包括 `content`、`duration`、`ratio`、`resolution` 和 `generate_audio`。
</Info>

文本对话路由请参阅 [Dola-Seed-SC](/cn/model-api/volcengine/dola-seed-sc)，本页仅说明视频生成。

## 模型 ID

| 版本                | MixRoute model ID                 |
| ----------------- | --------------------------------- |
| Seedance 2.5      | `doubao-seedance-2-5-260628`      |
| Seedance 2.0      | `doubao-seedance-2-0-260128`      |
| Seedance 2.0 Fast | `doubao-seedance-2-0-fast-260128` |
| Seedance 2.0 Mini | `doubao-seedance-2-0-mini-260615` |

模型可用性与账户有关，请使用 [模型广场](https://console.mixroute.ai/models) 中显示的完整 ID。

## 顶层字段

| 字段         | 类型      | 必填  | 说明                                                   |
| ---------- | ------- | --- | ---------------------------------------------------- |
| `model`    | string  | 是   | 模型表中的完整 MixRoute 模型 ID。                              |
| `prompt`   | string  | 是   | MixRoute 视频提示词。`metadata.content` 中存在文本项时，两处文本须保持一致。 |
| `asset`    | boolean | 按场景 | MixRoute 素材处理开关，不是厂商字段，放在请求顶层；纯文本示例使用 `false`。       |
| `metadata` | object  | 是   | 下列厂商字段的容器。                                           |

## 生成参数

| 字段                                  | 类型        | 必填 | 说明                                                                                                     |
| ----------------------------------- | --------- | -- | ------------------------------------------------------------------------------------------------------ |
| `metadata.content`                  | object\[] | 是  | 视频输入内容，包括文本、图像、视频和受支持的音频参考。纯文本生成须有文本项；媒体输入组合中的文本项在模型接口中为可选。                                            |
| `metadata.omni_reference_task_type` | string    | 否  | 仅 Seedance 2.5。默认 `auto`；取值为 `auto`、`reference`、`edit`、`extend`。指定模式可提前检查场景约束；声明类型与模型识别的意图不一致时仍可能异步失败。 |
| `metadata.resolution`               | string    | 否  | 输出分辨率档位，支持的取值和默认值见版本表；取值区分大小写。                                                                         |
| `metadata.ratio`                    | string    | 否  | 默认 `adaptive`；取值为 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`，并须遵守下方场景约束。                        |
| `metadata.duration`                 | integer   | 否  | 请求的视频时长，单位为秒，范围见版本表。受支持版本可用 `-1` 自动选择时长；Seedance 2.5 默认 `-1`，视频编辑必须为 `-1`。                             |
| `metadata.generate_audio`           | boolean   | 否  | 默认 `true`，生成与画面同步的单声道语音、音效或音乐；`false` 生成无声视频。                                                          |
| `metadata.watermark`                | boolean   | 否  | 默认 `false`。`true` 在右下角添加 AI 生成水印，`false` 不添加。                                                          |
| `metadata.output_format`            | string    | 否  | 仅 Seedance 2.5。默认 `mp4`；取值为 `mp4`、`mov`。MP4 适合通用播放，MOV 面向高色彩精度的后期处理，播放端须兼容相应编码。                        |
| `metadata.return_last_frame`        | boolean   | 否  | 默认 `false`。`true` 在任务结果中返回无水印 PNG 尾帧，像素尺寸与生成视频一致。                                                      |
| `metadata.callback_url`             | string    | 否  | 任务状态回调 URL。厂商通过 POST 发送其任务查询响应结构，状态包括 `queued`、`running`、`succeeded`、`failed`、`expired`。               |
| `metadata.execution_expires_after`  | integer   | 否  | 范围为 3600-259200 秒，默认 172800 秒（48 小时），从任务创建时计算；超时后任务终止并标记为 `expired`。                                   |
| `metadata.priority`                 | integer   | 否  | 仅 2.5 和 2.0。范围为 0-9，默认 0。数值越大，在同一推理接入点的队列中越优先；同优先级仍按先入先出，不中断运行中的任务，不能用于 `flex`。                        |
| `metadata.safety_identifier`        | string    | 否  | 稳定且唯一的终端用户标识，不超过 64 个英文字符；建议使用哈希标识，避免直接提供个人信息。                                                         |
| `metadata.tools`                    | object\[] | 否  | 仅 2.5 和 2.0。每个工具须提供 `type`，支持的取值为 `web_search`。模型自行决定是否搜索；查询结果中的 `usage.tool_usage.web_search` 返回搜索次数。 |

## 版本限制

| 版本                       | 分辨率                              | 默认分辨率  | 时长          | 参考数量上限（图像 / 视频 / 音频） |
| ------------------------ | -------------------------------- | ------ | ----------- | -------------------- |
| Seedance 2.5             | `480p` / `720p` / `1080p`        | `720p` | 4-30 s / -1 | 30 / 10 / 10         |
| Seedance 2.0             | `480p` / `720p` / `1080p` / `4k` | `720p` | 4-15 s / -1 | 9 / 3 / 3            |
| Seedance 2.0 Fast / Mini | `480p` / `720p`                  | `720p` | 4-15 s / -1 | 9 / 3 / 3            |

嵌套内容字段和媒体大小、格式限制参阅 [Seedance](/cn/api-reference/endpoint/seedance)。

## 场景约束

* 首帧、首尾帧和全模态参考是互斥场景，不要将首尾帧角色与 `reference_*` 角色混用。
* Seedance 2.5 的首帧、首尾帧、编辑和延长场景必须使用 `ratio="adaptive"`。编辑须提供至少一个 4-30 秒参考视频并使用 `duration=-1`，延长须提供参考视频。可选参数 `omni_reference_task_type` 可显式指定 `edit` 或 `extend`，也可保留自动判定。
* Seedance 2.0 的音频参考必须同时包含至少一个图像或视频参考。 Seedance 2.5 另支持仅音频参考。

## 调用示例

调用前设置环境变量 `MIXROUTE_API_KEY`，并将媒体占位值替换为可访问的素材。请求被接受后会创建计费任务；提交超时后不要自动重复提交。

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/video/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "A red cube slowly rotates on a white background. Static camera.",
  "asset": false,
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "A red cube slowly rotates on a white background. Static camera."
      }
    ],
    "duration": 4,
    "ratio": "9:16",
    "resolution": "480p",
    "generate_audio": false
  }
}'
```

### Python

```python theme={null}
import json
import os
import requests

payload = json.loads(r'''
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "A red cube slowly rotates on a white background. Static camera.",
  "asset": false,
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "A red cube slowly rotates on a white background. Static camera."
      }
    ],
    "duration": 4,
    "ratio": "9:16",
    "resolution": "480p",
    "generate_audio": false
  }
}
''')
response = requests.post(
    "https://api.mixroute.ai/v1/video/generations",
    headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
```

## 任务结果

保存提交响应中的 MixRoute 任务 ID，并调用 [查询视频任务](/cn/api-reference/endpoint/query-video-task)。提交成功表示任务已创建；任务完成后再读取生成结果。不同路由的响应封装和结果位置可能不同。