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

# seedance-2.5-ext 視頻生成

> 使用 seedance-2.5-ext 模型生成視頻，支持參考圖片、參考視頻和參考音頻

<Note>
  **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。
</Note>

`seedance-2.5-ext` 是 Seedance 2.5 系列的促銷渠道模型，支持文生視頻和多模態參考生成：

* 文生視頻、參考圖片生成
* 參考視頻和參考音頻聯合生成（不支持視頻編輯、延長和首尾幀模式）
* 接口為異步任務：提交後返回 `generation.task`，完成後通過[視頻任務狀態接口](../../tasks/video-status)獲取結果。

根據請求內容自動路由到最優上游：僅圖片或純文本時走低成本上游；攜帶參考視頻、參考音頻或超過 10 張參考圖時走全能力上游。

## 認證

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 認證：

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 請求參數

<ParamField body="model" type="string" default="seedance-2.5-ext" required>
  ToAPIs 公共模型名，固定使用 `seedance-2.5-ext`。
</ParamField>

<ParamField body="prompt" type="string">
  描述場景、鏡頭運動、主體動作、風格和聲音氛圍。引用素材時可按數組順序寫「圖片1」「視頻1」「音頻1」等標籤。
</ParamField>

<ParamField body="seconds" type="integer">
  輸出視頻時長（秒），範圍 `10`–`30`。兼容字段 `duration` 也可以使用，無需同時傳入。

  <Warning>
    攜帶參考視頻、參考音頻或超過 10 張參考圖片時不支持 `15` 秒；純文本或不超過 10 張圖片的請求不受此限制。
  </Warning>
</ParamField>

<ParamField body="size" type="string">
  輸出寬高比，支持 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`。兼容字段 `aspect_ratio` 也可以使用。
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  輸出分辨率，固定為 `720p`。
</ParamField>

<ParamField body="reference_image" type="string">
  單張參考圖片的公開 URL。多張時請改用 `reference_images`。
</ParamField>

<ParamField body="reference_images" type="string[]">
  參考圖片 URL 數組，最多 `30` 張。也可以使用 `image_with_roles`（`role` 為 `reference_image`）顯式傳入。
</ParamField>

<ParamField body="video_with_roles" type="object[]">
  參考視頻數組，最多 `10` 段。每項包含：

  * `url`：公開可訪問的視頻 URL
  * `role`：固定為 `reference_video`
</ParamField>

<ParamField body="audio_with_roles" type="object[]">
  參考音頻數組，最多 `10` 段。每項包含：

  * `url`：公開可訪問的音頻 URL
  * `role`：固定為 `reference_audio`

  音頻不能單獨作為輸入，請求中需要至少包含一張參考圖片或一段參考視頻。
</ParamField>

<ParamField body="callback_url" type="string">
  ToAPIs 任務完成回調地址，詳見[任務 Webhook](/docs/zh-Hant/api-reference/webhooks/task-webhooks)。
</ParamField>

<ParamField body="client_business_id" type="string">
  客戶側訂單號或業務任務 ID。提交後會隨任務保存，也可用 `GET /v1/videos/generations/{client_business_id}` 查詢。
</ParamField>

<ParamField body="trace_id" type="string">
  調用方自定義的鏈路追蹤 ID。
</ParamField>

## 素材組合規則

| 請求內容 | 是否支持 | 說明 |
| - | -: | - |
| 僅提示詞 | 是 | 文生視頻 |
| 參考圖片 ≤10 張 | 是 | 低成本上游 |
| 參考圖片 11–30 張 | 是 | 不支持 15 秒 |
| 參考視頻 / 參考音頻 | 是 | 不支持 15 秒；音頻需搭配圖片或視頻 |
| 首幀 / 尾幀 | 否 | 不支持首尾幀模式 |
| 視頻編輯 / 延長 | 否 | 請使用 `seedance-2-5` |

## 請求示例

### 文生視頻

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "電影感產品特寫，鏡頭緩慢推進，保留自然室內聲音。",
    "seconds": 10,
    "size": "16:9",
    "resolution": "720p"
  }'
```

### 參考圖片生成

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "讓圖片1中的人物走入雨夜街道，鏡頭跟隨。",
    "seconds": 12,
    "size": "9:16",
    "reference_images": [
      "https://example.com/character.png"
    ]
  }'
```

### 視頻和音頻聯合參考

```bash theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.5-ext",
    "prompt": "使用圖片1中的人物形象、視頻1的運鏡和音頻1的節奏生成視頻。",
    "seconds": 14,
    "size": "16:9",
    "reference_images": [
      "https://example.com/character.png"
    ],
    "video_with_roles": [
      {"url": "https://example.com/motion.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/rhythm.mp3", "role": "reference_audio"}
    ]
  }'
```

## 響應

<ResponseField name="id" type="string">任務 ID，用於查詢狀態。</ResponseField>
<ResponseField name="client_business_id" type="string">請求傳入該字段時返回。</ResponseField>
<ResponseField name="object" type="string">固定為 `generation.task`。</ResponseField>
<ResponseField name="model" type="string">本次請求的模型名。</ResponseField>
<ResponseField name="status" type="string">`queued`、`in_progress`、`completed` 或 `failed`。</ResponseField>
<ResponseField name="progress" type="integer">`0`–`100` 的任務進度。</ResponseField>
<ResponseField name="created_at" type="integer">創建時間戳。</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "tsk_vid_xxx",
    "object": "generation.task",
    "model": "seedance-2.5-ext",
    "status": "in_progress",
    "progress": 10,
    "created_at": 1781577600
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.