> ## 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](/zh-hant/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](/zh-hant/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，並呼叫 [查詢影片任務](/zh-hant/api-reference/endpoint/query-video-task)。提交成功表示任務已建立；任務完成後再讀取生成結果。不同路由的響應封裝和結果位置可能不同。