1
建立密鑰
在帳戶設定中產生密鑰。完整密鑰只顯示一次。
公共 API
把影片生成能力接入你的產品
建立安全的 API 密鑰，使用 Bearer 驗證提交 Seedance 影片任務，並輪詢任務直到儲存結果就緒。
快速開始
2
提交任務
使用 Bearer 驗證和唯一的 Idempotency-Key 傳送 POST 請求。
3
取得結果
輪詢任務，直到狀態變為 completed 或 failed。
身份驗證
每個請求都必須在 Authorization 標頭中帶上 API 密鑰。密鑰只能保存在伺服器端，不要寫入瀏覽器或行動應用程式。
http
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
Idempotency-Key: a-unique-id-per-requestAPI 密鑰以雜湊形式儲存，並可立即撤銷。
Seedance 影片生成
文字生成影片、首尾幀圖生影片和明確類型的參考素材工作流程共用一個非同步接口。
POST
/api/v1/video/generations參數
| 參數 | 類型 | 必填 | 預設 | 說明 |
|---|---|---|---|---|
mode | string | 否 | text-to-video | text-to-video · image-to-video · media-to-video |
model | string | 否 | seedance-2.0-fast | seedance-2.0 · seedance-2.0-fast · seedance-2.0-mini |
prompt | string | 是 | — | 3–4000 個字元 |
aspect_ratio | string | 否 | 16:9 | 1:1 · 21:9 · 4:3 · 3:4 · 16:9 · 9:16 · adaptive |
duration | number | 否 | 5 | 4–15 秒 |
resolution | string | 否 | 720p | 可用值取決於模型 |
image_url | HTTPS URL | 圖生影片 | — | 起始幀 |
end_image_url | HTTPS URL | 否 | — | 可選結束幀 |
reference_image_urls | string[] | 否 | [] | 最多 8 個公共 HTTPS URL |
reference_video_urls | string[] | 否 | [] | 最多 3 個公共 HTTPS URL |
reference_video_durations | number[] | 有參考影片時 | — | 每個 URL 對應一個整秒值；必須與伺服器完整解碼後的實測一致 |
generate_audio | boolean | 否 | true | 產生音軌 |
seed | integer | 否 | — | -1 – 4294967295 |
下載遠端素材前會原子預留付費積分；所有輸入素材合計不得超過 256 MB。參考影片會完整解碼以實測時長與尺寸，輸入素材複製到受管存儲後才提交供應商。確認在供應商接受前失敗時，會退回預留積分並刪除本次已上傳輸入；若無法確認供應商是否已接受，任務、積分與受管輸入會保留以待核對，只能使用相同 Idempotency-Key 重試，禁止為該請求建立新鍵。完成的輸出一定會先複製到站方受管存儲。image-to-video 僅接受首尾幀欄位；media-to-video 僅接受 reference_* 欄位。
請求
bash
curl -X POST https://seedancetovideo.com/api/v1/video/generations \
-H "Authorization: Bearer $SEEDANCE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: video-demo-001" \
-d '{
"mode": "text-to-video",
"model": "seedance-2.0-fast",
"prompt": "A cinematic glass train crossing a snowy mountain bridge",
"aspect_ratio": "16:9",
"duration": 5,
"resolution": "720p"
}'回應 202
json
{
"id": "idem_a3f8...",
"status": "processing",
"model": "seedance-2.0-fast",
"mode": "text-to-video",
"credits_used": 250,
"credits_refunded": 0,
"output": null,
"error": null
}2
查詢任務狀態
以合理間隔輪詢。任務狀態為 processing、completed 或 failed。
bash
curl https://seedancetovideo.com/api/v1/tasks/idem_a3f8... \
-H "Authorization: Bearer $SEEDANCE_API_KEY"回應 200
json
{
"id": "idem_a3f8...",
"status": "completed",
"model": "seedance-2.0-fast",
"mode": "text-to-video",
"credits_used": 250,
"credits_refunded": 0,
"output": {
"video_url": "https://cdn.seedancetovideo.com/...mp4"
},
"error": null,
"created_at": "2026-07-13T10:00:00.000Z",
"updated_at": "2026-07-13T10:03:12.000Z"
}積分價格
API 僅消耗密鑰擁有者的個人付費積分，不使用贈送積分。網頁與 API 購買共用同一個付費餘額。
標準輸出計價
| 模型 | 480p / 秒 | 720p / 秒 | 1080p / 秒 | 4K / 秒 |
|---|---|---|---|---|
seedance-2.0 | 30 積分 | 60 積分 | 150 積分 | 350 積分 |
seedance-2.0-fast | 25 積分 | 50 積分 | — | — |
seedance-2.0-mini | 15 積分 | 30 積分 | — | — |
參考影片計價
使用參考影片時，計費公式為（輸出秒數 + 完整解碼後由伺服器實測的參考影片秒數）× 請求輸出解析度對應費率。reference_video_durations 用於下載前預留積分，因此必填且必須與實測一致。
範例：seedance-2.0-fast 720p，輸出 5 秒並帶 3 秒參考影片，費用為 (5 + 3) × 30 = 240 積分。
| 模型 | 480p / 秒 | 720p / 秒 | 1080p / 秒 | 4K / 秒 |
|---|---|---|---|---|
seedance-2.0 | 20 積分 | 40 積分 | 100 積分 | 200 積分 |
seedance-2.0-fast | 15 積分 | 30 積分 | — | — |
seedance-2.0-mini | 10 積分 | 20 積分 | — | — |
錯誤碼
所有錯誤都使用統一的 JSON 結構。
json
{
"error": {
"code": "invalid_request",
"message": "prompt must contain between 3 and 4000 characters."
}
}| 錯誤碼 | HTTP | 說明 |
|---|---|---|
unauthorized | 401 | API 密鑰缺失、無效、過期或已撤銷。 |
invalid_request | 400 | 請求體、參數、任務 ID 或素材 URL 無效。 |
insufficient_credits | 402 | 付費積分不足。 |
not_found | 404 | 任務不存在或屬於其他帳戶。 |
rate_limited | 429 | 該密鑰在 60 秒內超過 30 個請求。 |
idempotency_conflict | 409 | 同一幂等密鑰已用於不同請求體。 |
payload_too_large | 413 | JSON 請求體超過 64 KiB。 |
service_busy | 503 | 供應商狀態暫時不可用或接受結果不確定；只能使用相同 Idempotency-Key 重試。 |
internal_error | 500 | 未預期的伺服器錯誤。 |
配合 Codex、Claude Code 或任何 Agent 使用
將機器可讀文件交給程式 Agent，它可以依照同一套公開契約完成整合。
常見問題
誰可以使用 API？
任何已登入帳戶都能建立密鑰；呼叫時必須有足夠的付費積分。
需要額外訂閱 API 套餐嗎？
不需要。建立密鑰免費，使用訂閱或一次性積分包為呼叫充值。
網頁與 API 共用積分嗎？
共用個人付費積分；註冊贈送和促銷積分不能用於 API。
生成失敗會怎樣？
符合退款條件且已確認的失敗任務會自動返還預留積分，credits_refunded 會顯示退款數量。若供應商接受結果不確定，積分會保持預留以待核對，只能使用相同 Idempotency-Key 重試。
速率限制是多少？
每個密鑰每 60 秒最多 30 個驗證請求；429 回應會帶 Retry-After。
輸出 URL 會保留多久？
托管 URL 用於交付，不是永久歸檔。請在任務完成後及時複製到你自己的存儲。
破壞性變更如何發佈？
當前契約使用 /api/v1 版本路徑。不相容變更會使用新的版本路徑，並發佈在開發者文件中。
API 密鑰以雜湊形式儲存，並可立即撤銷。