> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # SeeDance Videos Generation API 對接說明 > ByteDance Seedance Video Generation 集成指南 - XHuoAPI 本文將介紹一種 SeeDance Videos Generation API 對接說明，它是可以透過輸入自定義參數來生成SeeDance官方的視頻。 ## 申請流程 要使用 API，需要先到 [SeeDance Videos Generation API](https://api.xhuoapi.ai/documents/seedance-videos) 對應頁面申請對應的服務，進入頁面之後，點擊「Acquire」按鈕，如圖所示： ![](https://cdn.xhuoapi.ai/q6ytrc.png) 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。 在首次申請時會有免費額度贈送，可以免費使用該 API。 ## 基本使用 首先先了解下基本的使用方式，就是輸入提示詞 `content.text`、類型`content.type=text` 以及模型 `model`，便可獲得處理後的結果，具體的內容如下：

可以看到這裡我們設置了 Request Headers，包括： * `accept`：想要接收怎樣格式的響應結果，這裡填寫為 `application/json`，即 JSON 格式。 * `authorization`：調用 API 的密鑰，申請之後可以直接下拉選擇。 另外設置了 Request Body，包括： * `model`：生成視頻的模型，可選值：`doubao-seedance-1-0-pro-250528`、`doubao-seedance-1-0-pro-fast-251015`、`doubao-seedance-1-5-pro-251215`、`doubao-seedance-1-0-lite-t2v-250428`、`doubao-seedance-1-0-lite-i2v-250428`。 * `content`：輸入內容數組，`type` 可以是 `text` 或 `image_url`。 * `resolution`：輸出分辨率，可選 `480p` / `720p` / `1080p`。 * `ratio`：寬高比，可選 `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`。 * `duration`：視頻時長（秒），範圍 2–12。 * `seed`：隨機種子，整數，-1 到 4294967295。 * `camerafixed`：是否固定攝像頭，`true` / `false`。 * `watermark`：是否添加水印，`true` / `false`。 * `generate_audio`：是否生成有聲視頻，`true` / `false`，**僅 `doubao-seedance-1-5-pro-251215` 支持**。 * `service_tier`：推理模式，`default`（在線）或 `flex`（離線，價格為在線的 50%）。 * `return_last_frame`：是否在結果中返回視頻最後一幀圖片 URL。 * `execution_expires_after`：任務超時時間（秒），範圍 3600–259200。 * `callback_url`：異步回調地址，設置後 API 立即返回 `task_id`，任務完成時將結果 POST 到該地址。 選擇之後，可以發現右側也生成了對應代碼，如圖所示：

點擊「Try」按鈕即可進行測試，如上圖所示，這裡我們就得到了如下結果： ```json theme={null} { "success": true, "task_id": "ec22ae22-0140-4033-8c86-a48b536da595", "trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5", "data": { "task_id": "cgt-20251222005129-62fhb", "status": "succeeded", "video_url": "https://platform.cdn.xhuoapi.ai/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 返回結果一共有多個字段，介紹如下： * `success`，此時視頻生成任務的狀態情況。 * `task_id`，此時視頻生成任務ID。 * `trace_id`，此時視頻生成跟蹤ID。 * `data`，此時視頻生成任務的結果列表。 * `task_id`，此時視頻生成任務的伺服器端ID。 * `video_url`，此時視頻生成任務的視頻鏈接。 * `status`，此時視頻生成任務的狀態。 * `model`，生成視頻使用的模型。 可以看到我們得到了滿意的視頻信息，我們只需要根據結果中 `data` 的視頻鏈接地址獲取生成的SeeDance視頻即可。 另外如果想生成對應的對接代碼，可以直接複製生成，例如 CURL 的代碼如下： ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/seedance/videos' \ -H 'authorization: Bearer ${bearer_token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "content": [{"text":"A kitten yawning at the camera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}], "model": "doubao-seedance-1-0-pro-250528" }' ``` ## 內聯參數說明 在 `content[].text` 提示詞末尾，可以透過追加 `--parameter value` 的形式傳入生成參數（舊方式，弱校驗，填寫有誤時自動使用默認值）。完整參數列表如下： | 內聯參數 | 對應字段 | 說明 | 取值範圍 | | ---------- | ----------------- | ------- | ------------------------------------------------------------- | | `--rs` | `resolution` | 輸出分辨率 | `480p` / `720p` / `1080p` | | `--rt` | `ratio` | 寬高比 | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` | | `--dur` | `duration` | 視頻時長（秒） | 2–12 | | `--frames` | `frames` | 視頻幀數 | \[29, 289] 中滿足 25+4n 的整數 | | `--fps` | `framespersecond` | 幀率 | 僅支持 `24` | | `--seed` | `seed` | 隨機種子 | -1 到 4294967295 | | `--cf` | `camerafixed` | 是否固定攝像頭 | `true` / `false` | | `--wm` | `watermark` | 是否添加水印 | `true` / `false` | > **推薦做法**：直接在 Request Body 中使用對應的頂層字段（如 `resolution`、`ratio` 等），為強校驗模式，參數填寫有誤時會返回明確錯誤提示，更易於排查問題。 ## 生成有聲視頻 `doubao-seedance-1-5-pro-251215` 支持透過 `generate_audio` 參數生成帶音頻的視頻： ```json theme={null} { "model": "doubao-seedance-1-5-pro-251215", "content": [ { "type": "text", "text": "A girl holds a fox, the wind blows her hair, you can hear the sound of the wind" } ], "generate_audio": true, "ratio": "16:9", "duration": 5 } ``` 其他模型不支持此参数，传入后会被忽略。 ## 图生视频首帧 如果想图生视频任务，首先 `content` 参数需要包含 `type` 为 `image_url` 的项，`image_url` 字段必须为对象格式：`{"url": "https://..."}` 或 Base64 格式 `{"url": "data:image/png;base64,..."}`。 > **注意**：`image_url` 不支持直接传入字符串格式（如 `"image_url": "https://..."`），必须使用对象格式 `"image_url": {"url": "https://..."}`，否则会返回 400 错误。 对应的代码： ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "content": [ { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png" } }, { "type": "text", "text": "一位女孩怀抱着一只狐狸。她睁开眼睛，温柔地凝视着镜头，而狐狸则亲昵地回抱着她。当镜头缓缓拉远时，她的头发被风轻轻吹动。 --ratio adaptive --dur 5" } ], "model": "doubao-seedance-1-0-pro-250528" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 点击运行，可以发现会立即得到一个结果，如下： ``` { "success": true, "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39", "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4", "data": { "task_id": "cgt-20251222072003-x2259", "status": "succeeded", "video_url": "https://platform.cdn.xhuoapi.ai/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 可以看到，生成的效果是图生建视频的，结果与上文类似。 ## 图生视频首尾帧 如果想图生视频首尾帧， 首先参数`content`必须传入类型`image_url`,并且分别设置`role`为`first_frame`和`last_frame`，就可以指定如下内容： * role：指定首帧或者尾帧。 * image\_url * url 图片链接 同时 `content` 还需要输入类型`text`作为prompt提示词 对应的代码： ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedance-1-0-pro-250528", "content": [ { "type": "text", "text": "360度拍摄" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg" }, "role": "last_frame" } ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 点击运行，可以发现会立即得到一个结果，如下： ``` { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.xhuoapi.ai/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 可以看到，生成的效果是角色生成视频，结果与上文类似。 ## 异步回调 由于 SeeDance Videos Generation API 生成时间较长（约 1-2 分钟），可通过 `callback_url` 字段使用异步模式，避免 HTTP 连接长时间占用。 整体流程：客户端发起请求时指定 `callback_url`，API 立即返回包含 `task_id` 的响应；任务完成后，平台将生成结果以 POST JSON 的形式发送到 `callback_url`，结果中同样包含 `task_id` 以便关联。 ```json theme={null} { "task_id": "f7096c6c-9430-4392-8201-d259632d7afd" } ``` 任务完成时，平台推送到 `callback_url` 的内容如下： ```json theme={null} { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.xhuoapi.ai/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 结果中的 `task_id` 字段与请求时返回的一致，通过该字段即可实现任务的关联。 ## 错误处理 在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如： * `400 token_mismatched`：错误请求，可能是由于缺少或无效的参数。 * `400 api_not_implemented`：错误请求，可能是由于缺少或无效的参数。 * `401 invalid_token`：未授权，授权令牌无效或缺失。 * `429 too_many_requests`：请求过多，您已超出速率限制。 * `500 api_error`：内部服务器错误，服务器出现问题。 ### 错误响应示例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "获取失败" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 结论 通过本文档，您已经了解了如何使用 SeeDance Videos Generation API 可通过输入提示词以及参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。