Seedance 2.5，
整合至您的產品。

透過幾次請求，生成第一個影片。

將金鑰儲存為伺服器端環境變數 SEADANCE_API_KEY。為本次影片設定唯一的 SEADANCE_REQUEST_KEY（可使用 uuidgen 產生），重試時保留此值，並確保帳戶積分充足。以下範例將預扣 350 積分，生成一個 5 秒 720p 影片。請儲存回應中的 id，以便查詢生成結果。

export SEADANCE_API_KEY="sd_live_your_key"
# Keep this value for retries; choose a new value for a new video.
export SEADANCE_REQUEST_KEY="${SEADANCE_REQUEST_KEY:-$(uuidgen)}"

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos" \
  -H "Authorization: Bearer $SEADANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SEADANCE_REQUEST_KEY" \
  --data '{
  "model": "seedance-2.5",
  "mode": "text-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

本文件不會自動發起生成；傳送建立請求會使用您的帳戶積分。

在伺服器端完成身分驗證。

每次 API 呼叫都需帶上 Authorization: Bearer sd_live_…。請勿將金鑰放入瀏覽器、行動應用程式、公開儲存庫或前端程式碼。完整金鑰僅顯示一次，可隨時在 API 控制台撤銷。

預設金鑰權限：videos:write 用於上傳與生成；videos:read 用於模型資訊與任務查詢；account:read 用於積分查詢。帳戶的存取設定與限額會對所有金鑰共同生效。

建立影片任務。

使用 Content-Type: application/json，為每次預計生成的影片提供唯一的 Idempotency-Key。伺服器接收上游任務可能需要一些時間；連線逾時後，請以相同請求本文與相同金鑰重試。HTTP 202 表示任務已接收，不代表影片已完成。Idempotency-Key 長度為 1–128 個可列印的 ASCII 字元，不含空格。

這些欄位支援 Seedance 2.5 的文字轉影片、首尾幀、多模態參考、影片編輯與延長。目前可用功能與價格以 GET /models 回傳結果為準。

{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "firstFrameUrl": "YOUR_UPLOADED_PUBLIC_OBJECT_URL"
}

{
  "model": "seedance-2.5",
  "mode": "reference-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "referenceImageUrls": [
    "YOUR_UPLOADED_IMAGE_URL"
  ],
  "referenceVideoUrls": [
    "YOUR_UPLOADED_VIDEO_URL"
  ]
}

先上傳，再透過 URL 使用素材。

向 POST /uploads 提交 fileName、contentType、size（位元組數）與 kind（image、video 或 audio）。在 expiresAt 前，依 requiredHeaders 將原始檔案以 PUT 上傳至 uploadUrl。上傳成功後，在生成請求中使用 publicObjectUrl。素材必須屬於同一帳戶，不接受任意外部 URL 或 base64 輸入。

// Node.js 20+ · upload once, then use publicObjectUrl
import { readFile } from "node:fs/promises";

const bytes = await readFile("./first-frame.jpg");
const signed = await fetch("https://seedance3ai.dev/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEADANCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fileName: "first-frame.jpg", contentType: "image/jpeg",
    size: bytes.length, kind: "image",
  }),
});
const upload = await signed.json();
if (!signed.ok) throw new Error(JSON.stringify(upload));
const stored = await fetch(upload.uploadUrl, {
  method: "PUT", headers: upload.requiredHeaders, body: bytes,
});
if (!stored.ok) throw new Error("Upload failed");
console.log(upload.publicObjectUrl);
// Use this URL as firstFrameUrl in an image-to-video request.

申報的檔案大小與類型必須和實際上傳內容一致。上傳 URL 過期後需重新申請。生成前會驗證素材的長度、尺寸與格式。

查詢任務，直到生成完成。

透過 GET /videos/:id 取得任務狀態。建議每 5–10 秒查詢一次，遇到 succeeded 或 failed 時停止；如有 Retry-After，請依提示延遲重試。只能查詢目前帳戶透過 API 建立的任務。目前的整合方式為輪詢。

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

{
  "id": "a1b2c3d4-1234-4567-8901-abcdef123456",
  "status": "succeeded",
  "credits_reserved": 350,
  "created_at": "2026-10-27T00:00:00.000Z",
  "output": {
    "url": "https://your-result-host.example/video.mp4"
  },
  "error": null,
  "refund_status": "not_applicable"
}

影片生成前 output 為 null；任務失敗時回傳 error，可透過 refund_status 查看積分退還狀態。成功後請盡快下載結果。刪除影片不會重設生成請求：以原 Idempotency-Key 重送將回傳 410 video_deleted，不會再次生成。

整合前，先了解積分費用。

API 生成與網站共用帳戶積分及 Seedance 2.5 單價。請求被接收時會預扣積分，生成失敗後退回一次性積分餘額。任務建立前的參數驗證失敗，不會產生需計費的影片。

費用 = 輸出長度 × 輸出單價 + 參考影片長度 × 參考單價。參考影片由伺服器測量，總長度無條件捨去至整秒計費。原生音訊已包含在內。例如，5 秒 720p 影片需要 350 積分；若再使用 5 秒參考影片，則需要 600 積分。

curl --fail-with-body "https://seedance3ai.dev/api/v1/models" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

curl --fail-with-body "https://seedance3ai.dev/api/v1/credits" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

API 控制台可查看可用積分、呼叫紀錄與帳戶限額。請使用同一個帳戶透過網站價格頁補充積分，沒有獨立的 API 餘額或 API 儲值端點。可用積分充足即可呼叫，無需額外訂閱。訂閱到期與一次性積分規則和網站使用方式相同。

補充積分不會提高 API 請求頻率、同時執行任務數或每日限額，也不會自動恢復已停用的帳戶。每日額度依累計預扣積分計算，包含失敗後已退還的積分，於 UTC 00:00 重設。如需提高限額，請聯絡支援團隊。

安全重試，避免重複計費。

每個預計生成的影片使用一個 Idempotency-Key，結果明確前請保留它與完全相同的原始請求本文。新的金鑰代表新的生成請求。錯誤回應包含 error.code、error.message 與 request_id；聯絡支援團隊時請提供請求 ID。