Seedance 2.0 API

利用非同步任務創建、狀態輪詢、網路鉤子和智慧點數計費，將影片生成功能整合至您的產品中。

建立 API 金鑰 API 控制台

基本 URL

https://api.seedance2.ai

本頁內容

簡介

API 讓您可以透過程式方式提交 Seedance 2.0 影片生成任務。生成是非同步的：創建一個任務，立即收到一個任務 ID，然後透過輪詢任務端點或接收網路鉤子來獲取完成的影片。

非同步任務

輪詢適用於開發和簡單的整合。

網路鉤子就緒

建議在生產環境中使用網路鉤子，因為它們可以避免積極的輪詢，並在任務達到終端狀態時通知您的服務。

點數感知

點數在提交時預留。成功的任務將從該預留中扣除；失敗或超時的任務將自動退款。

驗證

在控制台建立一個 API 金鑰，並在每個請求中將其作為 Bearer 令牌發送。完整的金鑰只在創建時顯示一次。

Authorization: Bearer sk_live_xxxxxxxx

sk_live_

將 sk_live_ 金鑰用於生產流量。

sk_test_

使用 sk_test_ 金鑰進行沙盒整合測試，API 契約相同。

401

缺少、無效或已撤銷的金鑰會返回 invalid_api_key 和 HTTP 401。

快速入門

首先提交一個任務。任務被接受後，選擇一種結果傳送方法：輪詢任務端點，或透過網路鉤子接收終端結果。

提交任務

建立非同步影片任務並立即收到任務 ID。

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "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,
      "seed": -1
    }
  }'

結果選項：輪詢

當您的整合偏好明確輪詢時，請擷取任務狀態端點。

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

結果選項：網路鉤子

在提交任務時傳遞 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 建立影片任務。請求主體包含頂層模型、可選的 callback_url，以及一個包含提示和生成設定的 input 物件。

POST

/v1/videos/generations

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "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,
      "seed": -1
    }
  }'

生成模式

generation_type 控制接收哪些媒體輸入以及模型如何解釋它們。

模式	所需媒體	選用媒體	備註
`text-to-video`	提示	持續時間、長寬比、解析度、種子	僅限文字提示。image_urls、video_urls 和 audio_urls 不需要。
`image-to-video`	提示 + image_urls 陣列 (1-2 個圖片 URL)	持續時間、長寬比、解析度、種子	image_urls 必須是陣列。提供 1 個圖片 URL 作為第一幀，或 2 個圖片 URL 作為第一個和最後一個幀。影片和音訊將被忽略。
`reference-to-video`	提示 + 至少一張圖片或一段影片	在材料限制內的圖片、影片和音訊	音訊不能單獨與文字一起使用。提供音訊時，請至少添加一張圖片或一段影片。

text-to-video

當提示是唯一的創意輸入時，使用文字到影片。 (text-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "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,
      "seed": -1
    }
  }'

image-to-video

當 input.image_urls 是一個包含 1-2 個圖片 URL 的陣列時，使用圖片到影片：一個 URL 設定第一幀，兩個 URL 設定第一幀和最後一幀。影片和音訊參考在此模式下被忽略。 (image-to-video)

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "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

使用參考到影片以提供更豐富的參考圖片、影片和音訊。音訊不能單獨與文字一起使用；提供音訊時，請至少包含一張圖片或一段影片。 (reference-to-video)

材料限制

最多 9 張參考圖片
最多 3 段參考影片，總時長 <= 15 秒
最多 3 個參考音訊檔，總時長 <= 15 秒
所有類型材料總計不超過 12 個

支援的輸入組合

文字 + 圖片

文字 + 影片

文字 + 圖片 + 影片

文字 + 圖片 + 音訊

文字 + 影片 + 音訊

文字 + 圖片 + 影片 + 音訊

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "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": "1080p"
    }
  }'

請求參數

參數名稱、列舉值、端點路徑和範例是 API 契約的一部分。以下說明每個欄位的行為。

標頭

標頭	必填	說明	範例
`Authorization`	是	用於驗證請求的 Bearer API 金鑰。	`Bearer sk_live_xxx`
`Content-Type`	是	所有寫入請求都使用 JSON。	`application/json`

頂層欄位

欄位	類型	必填	預設	範圍／列舉	模式	範例
`model` 用於生成影片的模型變體。	string	是	-	seedance-2-0 \| seedance-2-0-fast	全部	`seedance-2-0`
`callback_url` 接收任務完成和失敗回調的 HTTPS 端點。	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 張圖片作為第一幀和最後一幀。對於參考轉影片，發送最多 9 張圖片作為視覺參考。 (image-to-video) (reference-to-video)	string[]	有條件的	[]	圖片到影片：1 或 2 張圖片。參考到影片：最多 9 張圖片。 (image-to-video) (reference-to-video)	image-to-video / reference-to-video	`["https://.../a.jpg"]`
`input.video_urls` 僅用於參考影片的公開可存取參考影片。您可以發送最多 3 個影片檔，其合併播放時間必須為 15 秒或更短。 (reference-to-video)	string[]	否	[]	最多 3 段影片。合併影片長度必須為 15 秒或更短。	reference-to-video	`[]`
`input.audio_urls` 僅用於參考影片的公開可存取參考音訊檔。您可以發送最多 3 個音訊檔，其合併播放時間必須為 15 秒或更短。 (reference-to-video)	string[]	否	[]	最多 3 個音訊檔。合併音訊長度必須為 15 秒或更短。	reference-to-video	`[]`
`input.duration` 輸出影片的長度（秒）。	int	否	5	4-15 秒	全部	`5`
`input.aspect_ratio` 輸出長寬比。自適應讓服務推斷最佳比例。	string	否	adaptive	16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| 調整	全部	`16:9`
`input.resolution` 輸出解析度層級。	string	否	720p	480p \| 720p \| 1080p	全部	`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` 確定性種子。使用 -1 表示隨機種子。	int	否	-1	-1 或 0-4294967295	全部	`-1`

點數會因解析度、持續時間、模型以及參考影片是否包含影片參考而異。創建回應返回的點數值是該任務實際預留的金額。 (reference-to-video)

查看點數定價

回應

這是 POST /v1/videos/generations 的成功回應。這表示任務已獲接受，並且點數已預留。使用返回的 taskId 輪詢 GET /v1/tasks/:id 或匹配完成或失敗回調。

POST /v1/videos/generations 成功回應

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

取得任務狀態

使用 GET /v1/tasks/:id 檢索目前任務狀態。輪詢間隔不得少於 10 秒。對於生產系統，建議使用網路鉤子。

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

完成任務回應

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seedance2.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-0",
  "billing_status": "refunded",
  "credits": 60,
  "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 為空。請在有效期結束前下載並儲存檔案。

網路鉤子

當 callback_url 存在時，當任務完成或失敗時，Seedance 會呼叫您的端點，並發送描述最終結果的 JSON 資料。如果您的端點返回非 2xx 回應或未在 15 秒內回應，則將重試傳遞最多 5 次。重試會重複使用相同的任務 ID，因此請按 ID 去重。一旦您安全地記錄了回調資料，請盡快返回 200 回應。

任務完成回調

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "results": ["https://cdn.seedance2.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-0",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 60
  }
}

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 去重，更新您自己的任務記錄，並快速回應。

callback_url 必須是 HTTPS 且不得指向私人、回送或連結本地網路範圍。

錯誤

當 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": 60,
    "available": 12
  }
}

代碼	HTTP	意義	重試？
`invalid_request`	400	缺少或無效的參數。	否，修正請求。
`invalid_api_key`	401	API 金鑰遺失、無效或已撤銷。	否，使用有效的金鑰。
`insufficient_credits`	402	點數不足。任務未獲接受或計費。	充值後。
`forbidden`	403	API 金鑰缺少所需的範圍。	否。
`not_found`	404	任務不存在或不屬於金鑰擁有者。	否。
`rate_limited`	429	請求速率超出限制。	是，遵循 Retry-After。
`internal_error`	500	伺服器錯誤。	是，稍後重試。

速率限制

速率限制是根據每個 API 金鑰以滑動視窗方式套用。生成預設為每分鐘 60 個請求；狀態查詢較為寬鬆。HTTP 429 回應包含 Retry-After。

生成

60/min

狀態查詢

更寬鬆

429 標頭

Retry-After

帳單與點數

API 在提交時預留點數，成功時扣款，失敗時退款。控制台使用頁面顯示 API 點數歷史、任務日誌和基於時間的使用統計資料。

已預留

任務接受時，點數會被檢查並預留。

已扣款

已完成任務結算現有預留。

已退款

失敗或超時的任務會自動退還預留點數。

在控制台檢查使用情況

查看 API 日誌、任務時間軸、點數歷史和基於時間的使用指標。

API 日誌