> ## 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 影片生成

> 使用 seedance-2-5 模型生成影片

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

Seedance 2.5 的公共模型名稱為 `seedance-2-5`，火山引擎上游模型 ID 為 `doubao-seedance-2-5-260628`。

* 支援文生影片、首幀/首尾幀圖生影片、影片編輯、影片延長及多模態參考生影片。
* 支援圖片、影片和音訊參考，也支援純音訊參考。
* 介面採用非同步任務；提交後返回 `generation.task`，完成後透過任務狀態介面取得影片。

樣片模式可先低成本生成 480p 樣片，再用該樣片生成 1080p 成稿，詳見[樣片模式](https://docs.toapis.com/docs/zh-Hant/api-reference/videos/seedance-2-5/draft.md)。

## Authorizations

**Authorization** `string` *required*

所有請求都需要 Bearer Token。請在 [API Key 管理頁面](https://toapis.com/console/token) 取得金鑰，並加入：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

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

ToAPIs 公共模型名稱，固定使用 `seedance-2-5`。

**prompt** `string`

描述場景、鏡頭運動、主體動作、風格與聲音氛圍。引用素材時使用「圖片1」「影片1」「音訊1」等標籤。

**video\_operation** `string` (default: generate)

視頻業務類型：`generate`、`edit` 或 `extend`。編輯和延長至少需要一個 `video_with_roles`；編輯使用 `duration=-1`，延長使用 `4`–`30` 或 `-1`。三種操作共用此接口。

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

客戶側訂單號或業務任務 ID。可用 `GET /v1/videos/generations/{client_business_id}` 查詢。

**duration** `integer`

輸出影片時長（秒），範圍為 `4`–`30`；`-1` 表示由模型自動選擇時長。編輯任務只能使用 `-1`，輸出時長與輸入影片基本一致；延長任務可使用 `4`–`30` 或 `-1`，此時按延長後的輸出總時長計算。

**aspect\_ratio** `string`

可選 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。編輯、延長和首尾幀任務按上游要求使用 `adaptive`。

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

相容模式圖片 URL 陣列。新接入建議使用 `image_with_roles`；兩個欄位不能同時傳送。

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

帶角色的圖片陣列，每項含必填 `url` 和 `role`。角色可為 `first_frame`、`last_frame` 或 `reference_image`，最多 30 張。首尾幀模式與參考圖模式不可混用。

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

參考影片陣列，每項含 `url`，角色固定為 `reference_video`，最多 10 段。

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

參考音訊陣列，每項含 `url`，角色固定為 `reference_audio`，最多 10 段；支援純音訊參考。

**resolution** `string`

解析度：`480p`、`720p` 或 `1080p`。

**output\_format** `string` (default: mp4)

支持 `mp4` 和 `mov`。

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

是否生成同步音訊。

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

是否在完成結果中返回生成影片的尾幀圖片。

**tools** `array`

可選工具：`[{ "type": "web_search" }]`。僅適用純文生影片，不能與圖片、影片或音訊輸入同時使用。

**callback\_url** `string`

ToAPIs 任務完成回呼地址，詳見[任務 Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md)。

**trace\_id** `string`

呼叫方自訂的鏈路追蹤 ID。

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

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

## 參考素材限制

最多共 50 個參考素材：圖片 30 張、影片 10 段、音訊 10 段。請使用明確角色，避免首幀/尾幀與參考素材被錯誤推斷。

> [!WARNING]
>
> 非法任務組合可能失敗。編輯和延長任務會明確指定上游任務類型，特殊限制不符合時在提交階段立即返回錯誤；其餘任務類型由模型按素材和提示詞判斷，不符合時在異步階段失敗並返回 `InvalidParameter.TaskTypeConstraint`。編輯、延長和首尾幀任務按上游要求將 `aspect_ratio` 設為 `adaptive`。

## 素材審核

請求帶有圖片, 影片或音訊素材時, 部分渠道會在提交生成前自動審核素材. 無需額外參數, 在原有媒體欄位中傳入素材 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.
* 成稿請求 (`draft_task_id`) 不送審.
* 舊的 `asset://` 素材引用已停用, 會返回 HTTP 400.

> [!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`

請求傳入此欄位時返回。

**object** `string`

固定為 `generation.task`。

**model** `string`

本次請求的模型名稱。

**status** `string`

`queued`、`in_progress`、`completed` 或 `failed`。

**progress** `integer`

`0`–`100` 的任務進度。

**created\_at** `integer`

建立時間戳。

```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-5","prompt":"電影感產品特寫，鏡頭緩慢推進。","duration":10,"aspect_ratio":"16:9","resolution":"720p","generate_audio":true}'
```

```json 影片延長請求 theme={null}
{
  "model": "seedance-2-5",
  "prompt": "向後延長影片1，鏡頭繼續推進並展示窗外的城市。",
  "video_operation": "extend",
  "duration": 11,
  "aspect_ratio": "adaptive",
  "output_format": "mov",
  "video_with_roles": [{"url": "https://example.com/source.mov", "role": "reference_video"}]
}
```

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


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