> ## 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 視頻生成

> 使用 seedance-2、seedance-2-fast 與 seedance-2-mini 模型生成視頻

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

* 支持 `seedance-2`、`seedance-2-fast` 與 `seedance-2-mini`
* 支持文生視頻、首幀/首尾幀圖生視頻與多模態參考生視頻；`seedance-2-mini` 的首尾幀與音頻開關能力也已開放
* 支持參考圖、參考視頻、參考音頻聯合控制；`seedance-2-mini` 最多支持 `9` 張圖、`3` 條視頻、`3` 條音頻
* 異步任務管理，提交後返回 `generation.task`，完成結果通過任務查詢接口獲取

## Authorizations

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 進行認證

獲取 API Key：訪問 [API Key 管理頁面](https://toapis.com/console/token) 獲取您的 API Key

使用時在請求頭中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: seedance-2)

視頻生成模型名稱

可用模型：

* `seedance-2` - 標準版，適合更高質量輸出與更完整的 Seedance 2 能力
* `seedance-2-fast` - 快速版，適合預覽、迭代和更低延遲場景
* `seedance-2-mini` - 輕量版，適合低成本草稿和多模態參考工作流，當前固定單次生成 `1` 個結果

**prompt** `string`

視頻內容描述

支持中英文輸入。建議明確描述場景、鏡頭運動、主體動作、風格和聲音氛圍。

建議：

* 中文儘量控制在 `500` 字以內
* 英文儘量控制在 `1000` 詞以內
* 需要引用參考素材時，使用“圖片1 / 視頻1 / 音頻1”的方式指代

**client\_business\_id** `string`

客戶側業務 ID，例如訂單號、流水號或您系統內的任務 ID。提交後會隨任務保存，後續可用該 ID 查詢狀態：
`GET /v1/videos/generations/{client_business_id}`。

也兼容放在 `metadata.client_business_id` 中，但推薦使用頂層字段。

**duration** `integer` (default: 0)

視頻時長（秒）

取值規則：

* `seedance-2`：`4-15`
* `seedance-2-fast`：`4-15`
* `seedance-2-mini`：`4-15`
* `0`：自動時長（僅 `seedance-2` / `seedance-2-fast`）
* `-1`：自動時長（僅 `seedance-2` / `seedance-2-fast`）

**aspect\_ratio** `string`

視頻寬高比

可選項：

* `21:9`
* `16:9`
* `4:3`
* `1:1`
* `3:4`
* `9:16`
* `adaptive`

建議優先使用 `aspect_ratio` 作爲對外字段。`adaptive` 表示由上游根據輸入素材自動選擇合適比例。

**image\_urls** `string[]`

兼容模式下的圖片 URL 數組

推薦優先使用 `image_with_roles`，這樣可以顯式聲明 `first_frame`、`last_frame` 或 `reference_image`。

兼容規則：

* 傳 1 張圖時，通常按首幀圖處理
* 傳多張圖時，角色推斷會帶來歧義，不建議用於新接入

> [!WARNING]
>
> * `image_urls` 不應與 `image_with_roles` 同時使用。
> * 新接入建議使用 `image_with_roles` 顯式聲明圖片用途，避免兼容推斷帶來的歧義。

**image\_with\_roles** `array`

帶角色的圖片數組

支持場景：

* `seedance-2` / `seedance-2-fast` / `seedance-2-mini`
  * 首幀圖生視頻：`first_frame` 1 張
  * 首尾幀圖生視頻：`first_frame` 1 張 + `last_frame` 1 張
  * 多模態參考生視頻：`reference_image` 1-9 張

**字段說明**

**url** `string` *required*

圖片 URL

支持：

* `https://...`

**role** `string` *required*

圖片角色

可選項：

* `first_frame` - 首幀圖
* `last_frame` - 尾幀圖
* `reference_image` - 參考圖

> [!WARNING]
>
> * `first_frame` 最多 1 張
> * `last_frame` 最多 1 張
> * `reference_image` 最多 `9` 張
> * 首幀/首尾幀模式不能與參考模式混用
> * `seedance-2-mini` 同樣支持 `first_frame`、`last_frame` 與 `reference_image`

**video\_with\_roles** `array`

帶角色的視頻數組

當前僅支持多模態參考模式使用 `reference_video`。

**字段說明**

**url** `string` *required*

視頻 URL

支持：

* `https://...`

**role** `string` *required*

固定爲：

* `reference_video`

限制：

* `seedance-2-mini` 最多 `3` 條參考視頻

**audio\_with\_roles** `array`

帶角色的音頻數組

當前僅支持多模態參考模式使用 `reference_audio`。

**字段說明**

**url** `string` *required*

音頻 URL

支持：

* `https://...`

**role** `string` *required*

固定爲：

* `reference_audio`

限制：

* `seedance-2-mini` 最多 `3` 段參考音頻

> [!WARNING]
>
> `audio_with_roles` 不能單獨使用，至少還需要一個圖片或視頻參考輸入。

**resolution** `string` (default: 720p)

視頻分辨率

可選項：

* `seedance-2`：`480p`、`720p`、`1080p`、`4k`
* `seedance-2-fast`：`480p`、`720p`
* `seedance-2-mini`：`480p`、`720p`

**generate\_audio** `boolean` (default: true)

是否生成同步音頻

* `true`：生成帶音頻的視頻
* `false`：生成無聲視頻

`seedance-2-mini` 同樣支持該字段。

**return\_last\_frame** `boolean` (default: false)

是否返回生成視頻的尾幀圖像。

設為 `true` 後，任務完成時可從狀態查詢響應的 `result.data[0].last_frame_url` 獲取尾幀圖像 URL。

**tools** `array`

配置模型可調用的工具。目前 Seedance 2 系列僅支持聯網搜索：

```json theme={null}
[{ "type": "web_search" }]
```

啓用後，模型會根據提示詞自主判斷是否搜索互聯網內容。實際搜索次數通過狀態查詢響應的 `usage.tool_usage.web_search` 獲取，值爲 `0` 表示未執行搜索。

> [!WARNING]
>
> `tools` 僅支持純文本生成視頻請求，不能與圖片、視頻或音頻輸入同時使用。

**seed** `integer`

隨機種子，用於控制生成隨機性

**callback\_url** `string`

ToAPIs 標準任務完成回調。需先設定 Token URL 與密鑰，只允許同源覆蓋。詳見 [Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md)。

**trace\_id** `string`

調用方自定義透傳 ID

調用方追蹤欄位，與 Webhook 是否啟用無關。

**disable\_nsfw** `boolean` (default: false)

設為 `true` 時禁止生成 NSFW 內容。

## 素材審核

請求帶有圖片, 視頻或音頻素材時, 部分渠道會在提交生成前自動審核素材. 無需額外參數, 在原有媒體欄位中傳入素材 URL 即可.

* 請求受理後立即返回視頻任務. 需要審核時任務維持 `queued`, 本次請求的素材全部通過後才提交生成. 首次審核可能需要數分鐘, 同一使用者在同一渠道重複使用相同 URL 時會重用審核結果.
* 每輪素材準備預設最長 20 分鐘. 素材被拒絕或準備逾時會結束任務, 狀態為 `failed`, 原因見 `error.message`. 審核未通過不收取視頻生成費用.
* 素材須為公網 HTTP(S) URL, 不接受 Base64 與本機路徑. 圖片建議不超過 20 MB (部分渠道最高 30 MB), 視頻與音頻不超過 100 MiB; 各模型原有的格式限制不變.
* 需要審核的渠道會在受理時驗證素材: URL 帶有帳號密碼或超過 2048 位元組, 同一 URL 被用作不同型別, 或單次請求的素材引用超過 64 個時, 直接返回 HTTP 400, `error.code` 為 `invalid_private_assets`.
* 平台依 URL 識別素材. 檔案內容變更後請改用新的 URL.
* 舊的 `asset://` 素材引用已停用, 會返回 HTTP 400.

## 輸入組合規則

支持的典型輸入組合：

* 純文本：文生視頻
* 文本 + 1 張首幀圖：首幀圖生視頻
* 文本 + 首幀圖 + 尾幀圖：首尾幀圖生視頻
* 文本 + 參考圖：多模態參考生視頻
* 文本 + 參考視頻：視頻參考生視頻
* 文本 + 參考圖 + 參考音頻：多模態參考生視頻
* 文本 + 參考圖 + 參考視頻 + 參考音頻：多模態參考生視頻

> [!WARNING]
>
> 三種模式互斥：
>
> * 首幀圖生視頻
> * 首尾幀圖生視頻
> * 多模態參考生視頻
>
> `seedance-2-mini` 也支持首幀 / 首尾幀模式；需要首尾幀控制時請使用 `image_with_roles` 顯式傳入 `first_frame` / `last_frame`。

## 能力與約束

| 項目 | seedance-2 | seedance-2-fast | seedance-2-mini |
| - | - | - | - |
| 主要定位 | 更高質量與更長時長 | 更快生成與更低延遲 | 低成本草稿與多模態參考 |
| 時長 | `4-15` 秒，支持自動時長 | `4-15` 秒，支持自動時長 | `4-15` 秒 |
| 分辨率 | `480p` / `720p` / `1080p` / `4k` | `480p` / `720p` | `480p` / `720p` |
| 圖片角色 | `first_frame` / `last_frame` / `reference_image` | `first_frame` / `last_frame` / `reference_image` | `first_frame` / `last_frame` / `reference_image` |
| 視頻角色 | `reference_video` | `reference_video` | `reference_video` |
| 音頻角色 | `reference_audio` | `reference_audio` | `reference_audio` |
| 首尾幀模式 | 支持 | 支持 | 支持 |
| 參考圖上限 | `9` | `9` | `9` |
| 參考視頻上限 | 以實際通道能力爲準 | 以實際通道能力爲準 | `3` |
| 參考音頻上限 | 以實際通道能力爲準 | 以實際通道能力爲準 | `3` |
| 同步音頻 | `generate_audio` | `generate_audio` | `generate_audio` |
| ToAPIs 回調 | `callback_url`（`trace_id` 可選追蹤） | `callback_url`（`trace_id` 可選追蹤） | `callback_url`（`trace_id` 可選追蹤） |

> [!NOTE]
>
> `seedance-2-mini` 當前固定單次生成 `1` 個結果，不暴露 `count` / `n`。首尾幀控制請通過 `image_with_roles` 的 `first_frame` / `last_frame` 表達。

> [!NOTE]
>
> 完成後透過[影片任務查詢](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/video-status.md#seedance-原始位址與備用位址)取得結果. 啟用原始位址交付時優先使用 `result.data[].url`; 主要位址無法存取時, 再使用可選的 `fallback_url`. 尾幀對應 `last_frame_url` 和 `fallback_last_frame_url`, 備用欄位僅在副本可用時回傳.

## Response

**id** `string`

任務 ID，用於查詢任務狀態。

**client\_business\_id** `string`

客戶側業務 ID。僅當請求中傳入 `client_business_id` 時返回。

**object** `string`

對象類型，固定爲 `generation.task`。

**model** `string`

本次請求使用的模型名稱。

**status** `string`

任務狀態：`queued`、`in_progress`、`completed` 或 `failed`。

**progress** `integer`

任務進度百分比（`0-100`）。

**created\_at** `integer`

任務創建時間戳。

> [!NOTE]
>
> 提交接口返回的是基礎任務對象；當任務完成後，請使用 [獲取視頻任務狀態](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/video-status.md) 獲取 `completed_at`、`expires_at` 以及 `result.type = "video"` / `result.data[].url` / `result.data[].format`。啓用 `return_last_frame` 時，尾幀 URL 位於 `result.data[0].last_frame_url`；啓用 `web_search` 時，搜索次數位於 `usage.tool_usage.web_search`。

```bash cURL（seedance-2-mini 多模態參考） theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2-mini",
    "client_business_id": "order_20260616_001",
    "prompt": "保持圖片1中的人物形象，參考視頻1的運鏡和音頻1的節奏，生成一段室內產品口播短視頻。",
    "duration": 10,
    "aspect_ratio": "16:9",
    "image_with_roles": [
      {"url": "https://example.com/ref-image-1.jpg", "role": "reference_image"}
    ],
    "video_with_roles": [
      {"url": "https://example.com/ref-video-1.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/ref-audio-1.mp3", "role": "reference_audio"}
    ],
    "resolution": "480p"
  }'
```

```bash cURL（首尾幀圖生視頻） theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2",
    "prompt": "鏡頭從窗邊花束慢慢推到餐桌中央，畫面色調溫暖柔和。",
    "duration": 5,
    "aspect_ratio": "16:9",
    "image_with_roles": [
      {"url": "https://example.com/first-frame.png", "role": "first_frame"},
      {"url": "https://example.com/last-frame.png", "role": "last_frame"}
    ],
    "resolution": "720p",
    "generate_audio": false
  }'
```

```bash cURL（文生視頻） theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2",
    "prompt": "微距鏡頭拍攝一隻玻璃蛙停在葉片上，鏡頭緩慢切到透明腹部與跳動心臟，紀錄片風格。",
    "duration": 11,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'
```

```bash cURL（Fast 版本快速預覽） theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2-fast",
    "prompt": "一隻柴犬在雨後的霓虹街頭奔跑，地面倒映彩色燈光。",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-mini",
        "prompt": "保持人物形象一致，參考圖片和視頻的節奏，生成一段簡短室內廣告視頻",
        "duration": 8,
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "image_with_roles": [
            {"url": "https://example.com/ref.png", "role": "reference_image"}
        ],
        "video_with_roles": [
            {"url": "https://example.com/ref.mp4", "role": "reference_video"}
        ],
    },
)

print(response.json())
```

```json 200 theme={null}
{
  "id": "tsk_vid_xxx",
  "client_business_id": "order_20260616_001",
  "object": "generation.task",
  "model": "seedance-2-mini",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1781577600
}
```


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