Seedance API

利用 Seedance 2.5 或 Seedance 2.0、非同步任務、Webhook 和點數扣抵機制，將影片生成功能無縫整合至您的產品中。

基礎 URL

https://api.seevio.ai

本頁索引

簡介

本 API 可讓您以程式化方式提交 Seedance 2.5 和 Seedance 2.0 影片生成任務。推薦使用最新一代的 Seedance 2.5 模型，其支援文字生成影片、首影格或首尾影格的圖片生成影片，以及多模態參考生成影片。影片生成採非同步方式處理：提交申請後會立即收到任務 ID，接著您可透過輪詢任務端點或設定 Webhook 來獲取生成完畢的影片。

非同步任務

輪詢適合開發階段及簡單的系統整合。

支援 Webhook

生產環境推薦使用 Webhook，不僅能避免頻繁輪詢造成的效能浪費，還能在任務進入終端狀態時主動通知您的服務。

智慧點數扣抵

點數會在提交任務時預先保留。任務成功後才會正式扣除點數；若任務失敗或逾時，預留的點數將會自動退回。

身分驗證

請至控制台建立 API 金鑰，並在每次發送請求時，將其作為 Bearer 權杖（Token）傳送。完整的金鑰僅會在建立時顯示一次，請妥善保存。

Authorization: Bearer sk_live_xxxxxxxx

sk_live_

正式環境流量請使用 sk_live_ 金鑰。

sk_test_

沙盒環境整合測試請使用 sk_test_ 金鑰，兩者採用相同的 API 協定。

401

若金鑰遺漏、無效或已被撤銷，系統將回傳 invalid_api_key 錯誤與 HTTP 401 狀態碼。

快速上手

首先請提交影片生成任務。當任務成功受理後，您可以選擇以下其中一種方式獲取生成結果：主動輪詢任務狀態端點，或是透過 Webhook 自動接收最終結果。

1. 提交任務

建立非同步影片生成任務，並立即取得任務 ID。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

2. 獲取結果方式 A：輪詢

若您的系統偏好主動查詢，可定時請求任務狀態端點以獲取最新進度。

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

2. 獲取結果方式 B：Webhook

在提交任務時帶入 callback_url。當任務完成或失敗時，系統會自動發送回呼通知，以便您更新內部的任務記錄。

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

建立影片任務

發送 POST /v1/videos/generations 請求以建立影片任務。請求主體包含最外層的 model、選填的 callback_url，以及含有提示詞（prompt）和生成設定的 input 物件。

POST

/v1/videos/generations

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

生成模式

generation_type 用於控制系統接受哪些媒體輸入，以及模型解讀這些輸入的方式。

Seedance 2.5 核心功能

seedance-2-5

將 model 設為 seedance-2-5，即可生成長度 4 到 30 秒、解析度為 480p 或 720p 的影片。

文字生成影片：支援自動適應（adaptive）或指定 16:9、9:16、1:1、4:3、3:4、21:9 等畫面比例
圖片生成影片：支援單張圖片（首影格）或兩張圖片（首尾影格）輸入；畫面比例必須設為 adaptive
參考生成影片（多模態）：最多支援 30 張圖片、10 支影片及 10 個音訊檔案，素材總數上限為 50 個
每個參考影片或音訊素材長度須為 2-30 秒；參考影片總時長與參考音訊總時長亦分別不得超過 30 秒
支援純音訊參考輸入以及 return_last_frame 參數；此模式不支援 seed 參數

生成模式	必要媒體輸入	選填媒體輸入	備註
`text-to-video`	prompt	duration, aspect_ratio, resolution, seed	僅需提供文字提示詞。無須傳入 image_urls、video_urls 或 audio_urls。
`image-to-video`	prompt + image_urls 陣列（1-2 個圖片 URL）	duration, aspect_ratio, resolution, seed	image_urls 必須為陣列。傳入 1 個圖片 URL 作為首影格，或傳入 2 個圖片 URL 分別作為首尾影格。影片與音訊輸入將被忽略。
`reference-to-video`	prompt + 至少一個圖片、影片或音訊參考	符合素材限制的圖片、影片及音訊	Seedance 2.5 支援僅包含音訊的參考。使用 Seedance 2.0 時，若傳入音訊，必須同時提供至少一個圖片或影片。

text-to-video

當提示詞（prompt）為唯一的創意輸入來源時，請使用文字生成影片模式。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

image-to-video

當 input.image_urls 陣列包含 1 到 2 個圖片 URL 時，請使用圖片生成影片模式：提供 1 個 URL 時作為首影格，提供 2 個 URL 時則分別作為首尾影格。在此模式下，傳入的影片和音訊參考將被自動忽略。

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

reference-to-video

若需使用參考圖片、影片或音訊進行更精準的畫面引導，請使用參考生成影片模式。Seedance 2.5 支援僅提供音訊作為參考；而 Seedance 2.0 在提供音訊時，必須同時提供至少一個圖片或影片參考。

素材限制說明

Seedance 2.5：最多 30 張參考圖片
Seedance 2.5：最多 10 支參考影片，每支 2-30 秒，總長度不超過 30 秒
Seedance 2.5：最多 10 個參考音訊，每個 2-30 秒，總長度不超過 30 秒
Seedance 2.5：所有類型的參考素材總數上限為 50 個
Seedance 2.0 系列模型維持既有上限：9 張圖片、3 支影片、3 個音訊，且影片/音訊各組總長度不超過 15 秒

支援的輸入組合

文字 + 圖片

文字 + 影片

文字 + 音訊 (Seedance 2.5)

文字 + 圖片 + 影片

文字 + 圖片 + 音訊

文字 + 影片 + 音訊

文字 + 圖片 + 影片 + 音訊

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "720p"
    }
  }'

請求參數

參數名稱、列舉值（Enum）、端點路徑及程式範例均為 API 協定的一部分，請嚴格遵守。下方說明詳細介紹了各欄位的行為特性。

標頭

標頭	必要性	說明	範例
`Authorization`	是	用於 API 身分驗證的 Bearer 金鑰。	`Bearer sk_live_xxx`
`Content-Type`	是	所有寫入請求均需使用 JSON 格式。	`application/json`

最外層欄位

欄位名稱	型態	必要性	預設值	範圍 / 列舉值	適用模式	範例
`model` 用於生成的模型版本。請輸入 seedance-2-5 使用 Seedance 2.5，輸入 seedance-2-0 使用 Seedance 2.0，輸入 seedance-2-0-fast 使用 Seedance 2.0 Fast，或輸入 seedance-2-0-mini 使用 Seedance 2.0 Mini。	string	是	-	seedance-2-5 \| seedance-2-0 \| seedance-2-0-fast \| seedance-2-0-mini	全部	`seedance-2-5`
`callback_url` 用來接收任務成功或失敗通知的 HTTPS API 端點。	string	否	-	HTTPS URL，不支援私有網路	全部	`https://your-domain.com/hook`
`input` 生成相關設定及媒體參考素材。	object	是	-	-	全部	`-`

`input.*` 欄位

欄位名稱	型態	必要性	預設值	範圍 / 列舉值	適用模式	範例
`input.prompt` 用來描述生成影片內容的文字提示詞。	string	是	-	非空字串	全部	`a cat surfing`
`input.generation_type` 生成模式。預設為 text-to-video。	string	否	text-to-video	text-to-video \| image-to-video \| reference-to-video	-	`image-to-video`
`input.image_urls` 可公開存取的圖片 URL。在圖片生成影片模式下，傳入 1 張作為首影格，傳入 2 張則分別作為首尾影格。在參考生成影片模式下，Seedance 2.5 最多支援 30 張圖片，Seedance 2.0 最多支援 9 張。	string[]	條件性適用	[]	圖片生成影片：1 或 2 張圖片。參考生成影片：Seedance 2.5 最多 30 張；Seedance 2.0 最多 9 張。	image-to-video / reference-to-video	`["https://.../a.jpg"]`
`input.video_urls` 僅適用於參考生成影片模式，且必須為可公開存取的影片 URL。Seedance 2.5 最多支援 10 支影片，每支長度 2-30 秒且總播放時間 <= 30 秒。Seedance 2.0 最多支援 3 支且總播放時間 <= 15 秒。	string[]	否	[]	Seedance 2.5：最多 10 支影片，每支 2-30 秒，總長度 <= 30 秒。Seedance 2.0：最多 3 支，總長度 <= 15 秒。	reference-to-video	`[]`
`input.audio_urls` 僅適用於參考生成影片模式，且必須為可公開存取的音訊 URL。Seedance 2.5 最多支援 10 個音訊檔案，每個長度 2-30 秒且總播放時間 <= 30 秒（支援純音訊參考）。Seedance 2.0 最多支援 3 個且總播放時間 <= 15 秒。	string[]	否	[]	Seedance 2.5：最多 10 個音訊，每個 2-30 秒，總長度 <= 30 秒。Seedance 2.0：最多 3 個，總長度 <= 15 秒。	reference-to-video	`[]`
`input.duration` 生成影片的目標長度（秒）。	int	否	5	Seedance 2.5：4-30 秒。Seedance 2.0：4-15 秒。	全部	`5`
`input.aspect_ratio` 輸出影片的畫面比例。設為 adaptive 將由系統自動判斷最佳比例。Seedance 2.5 的圖片生成影片模式僅支援 adaptive。	string	否	adaptive	16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| adaptive	全部	`16:9`
`input.resolution` 輸出影片的解析度級別。	string	否	720p	Seedance 2.5: 480p \| 720p。Seedance 2.0: 480p \| 720p \| 1080p \| 4k（依具體模型變體而定）。	全部	`720p`
`input.generate_audio` 模型是否在支援的狀況下自動生成相配的音效/音軌。	boolean	否	true	true \| false	全部	`true`
`input.watermark` 是否在輸出的影片中添加浮水印。	boolean	否	false	true \| false	全部	`false`
`input.web_search` 在支援的狀況下，是否啟用聯網搜尋增強技術。	boolean	否	false	true \| false	全部	`false`
`input.return_last_frame` 是否在結果中一併回傳最後一影格的圖片 URL（若支援）。	boolean	否	false	true \| false	全部	`false`
`input.seed` 用於 Seedance 2.0 系列模型的隨機數種子。Seedance 2.5 不支援此欄位，請勿傳入。	int	否	-1	-1 或 0-4294967295	全部	`-1`

所需點數會依據解析度、影片長度、所選模型以及參考生成影片中是否包含影片參考而有所不同。建立任務回應中所回傳的 credits 值，即為該任務實際預扣的點數額度。

查看點數定價

回應範例

這是 POST /v1/videos/generations 請求成功時的回傳格式，代表系統已成功受理該任務並預扣點數。您可以使用回傳的 taskId 來輪詢 GET /v1/tasks/:id，或用來核對 Webhook 傳送的任務成功/失敗回呼。

POST /v1/videos/generations 成功回應範例

{
  "taskId": "3f2aK9mR...",
  "credits": 100
}

取得任務狀態

使用 GET /v1/tasks/:id 來取得目前的任務狀態。輪詢頻率建議不要高於每 10 秒一次。若為生產環境系統，建議優先採用 Webhook 接收狀態。

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

任務生成成功回應

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任務生成失敗回應

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

狀態值	代表意義
`status=queued`	任務已受理，正排隊等待發送或處理。
`status=generating`	系統正在進行影片生成。
`status=completed`	影片生成成功，可在 data.results 中取得成品 URL。
`status=failed`	影片生成失敗或處理逾時。
`billing_status=reserved`	任務進行中，對應點數處於預扣狀態。
`billing_status=charged`	任務順利完成，點數已正式扣除並結算。
`billing_status=refunded`	任務失敗或逾時，預扣的點數已自動退回帳戶。
`billing_status=refund_failed`	退款交易異常，需要人工介入處理。

超過 video_expires_at 之後，data.results 內容將會被清空。請務必在到期日前下載並儲存生成的影片檔案。

Webhooks

若請求中帶有 callback_url，Seedance 就會在任務完成或失敗時，向您設定的端點發送包含最終結果的 JSON 資料。若您的端點回傳非 2xx 狀態碼或未在 15 秒內回應，系統將會嘗試重新傳送，最多重試 5 次。重試時會使用相同的 task id，請務必在您的系統中進行去重（De-duplicate）處理。一旦您的系統安全寫入回呼資料後，請立即回傳 200 回應。

任務生成成功回呼

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任務生成失敗回呼

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

請驗證回呼資料的欄位結構、依據 id 進行去重、更新您內部的任務記錄，並儘速回傳 HTTP 回應。

callback_url 必須使用 HTTPS 協定，且不可指向私有網路、本機環回（loopback）或本機連結（link-local）等 IP 範圍。

錯誤處理

當 API 請求本身失敗（例如：參數錯誤、API 金鑰失效、點數不足、觸發頻率限制或找不到任務）時，POST /v1/videos/generations 和 GET /v1/tasks/:id 會回傳此錯誤格式。部分錯誤會根據實際狀況，提供額外的輔助欄位如 required、available 或 retry_after。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

錯誤碼	HTTP 狀態碼	錯誤說明	是否可重試？
`invalid_request`	400	遺漏必填參數，或傳入了無效的參數值。	否。請修正請求內容後再試。
`invalid_api_key`	401	API 金鑰遺漏、無效或已被撤銷。	否。請使用有效的 API 金鑰。
`insufficient_credits`	402	帳戶點數不足。任務無法被受理，亦不會扣除任何點數。	請於加值後重試。
`forbidden`	403	該 API 金鑰權限不足，無法執行此操作。	否。
`not_found`	404	找不到該任務，或該任務不屬於目前金鑰的擁有者。	否。
`rate_limited`	429	API 請求頻率已超載。	是。請依據 Retry-After 標頭指示的時間稍後重試。
`internal_error`	500	伺服器內部發生異常。	是。請稍後重試。

頻率限制

頻率限制是以滑動視窗（sliding window）演算法針對個別 API 金鑰進行計算。影片生成限制預設為每分鐘 100 次請求；狀態查詢的限制則相對寬鬆。當觸發 HTTP 429 限制時，回應標頭中會包含 Retry-After 資訊。

影片生成限制

100/分鐘

狀態查詢限制

更寬鬆的額度

429 回應標頭

Retry-After

計費與點數

API 計費機制採「提交時預扣點數、成功後正式扣款、失敗則原額退回」。您可在控制台的用量頁面中，查看 API 點數交易紀錄、詳細的任務日誌以及視覺化的圖表用量統計。

預扣機制 (Reserved)

當任務成功受理時，系統會立即檢查並預先保留所需點數。

正式扣款 (Charged)

任務順利完成後，系統會將預扣的點數進行結算並正式扣除。

退回機制 (Refunded)

若任務不幸失敗或處理逾時，系統會自動退回先前預扣的所有點數。

在控制台中查看詳細用量

即時監控 API 日誌、任務時間軸、點數消費歷史以及各時段的用量指標。

查看 API 日誌