說明文件

使用 Seevio API 進行開發

為您的產品輕鬆引進影片生成功能。只需選擇模型、提交請求，即可透過輪詢或 Webhook 取得生成結果。

建立 API 金鑰 API 控制台

選擇模型

每個模型的參考指南皆包含完整的參數、計費方式與實用範例。您只需在單一模型頁面上，即可完成所有的整合開發。

Seedance 2.5

480p · 720p · 1080p

4–30 秒

閱讀模型說明文件

Seedance 2.0

480p · 720p · 1080p · 4k

4–15 秒

閱讀模型說明文件

Seedance 2.0 Fast

480p · 720p

4–15 秒

閱讀模型說明文件

Seedance 2.0 Mini

480p · 720p

4–15 秒

閱讀模型說明文件

身分驗證

請至控制台建立 API 金鑰。完整的金鑰內容僅會顯示一次，請妥善保存在您的伺服器端，並在每次發送請求時，將其作為 Bearer 權杖（Token）帶入標頭。

建立 API 金鑰 API 控制台

基本 URL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

在執行這些程式碼範例之前，請先設定 SEEVIO_API_KEY 環境變數。JavaScript 範例將在您的 Node.js 伺服器端執行；Python 範例則使用 requests 套件。

快速上手

本範例示範如何使用 Seedance 2.5 生成一段 5 秒、720p 的影片。若要查看完整的生成模式與參數限制，請參閱個別模型的參考指南。

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

建立任務的回傳範例

接受上述請求後，API 會傳回此 JSON 回應。taskId 為後續查詢狀態時使用的任務識別碼；credits 為此任務預扣的額度。此回應僅確認任務已成功建立，並不代表影片已製作完成。您需要輪詢任務狀態或使用 Webhook 來接收影片結果。

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

查詢任務

GET https://api.seevio.ai/v1/tasks/{taskId}

請將範例中的 ID 替換為建立任務時回傳的 taskId。查詢功能僅能存取該 API 金鑰擁有者建立的任務；存取無權限或不存在的 ID 會回傳 HTTP 404。

建議每 10–20 秒輪詢一次，若收到 HTTP 429 則請放慢頻率（Backoff），並在狀態轉為 completed 或 failed 時停止。生產環境建議優先採用 Webhook。下方的每個程式碼範例僅執行單次查詢。

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

狀態	說明與限制
`queued`	已接收並等待提交處理。
`generating`	影片正在生成中。
`completed`	生成成功。請在過期前下載 data.results 中的影片。
`failed`	生成失敗。請檢查 failed_reason 和 billing_status。

欄位	類型	說明與限制
`id`	string	任務識別碼。即建立任務回應中的 taskId。
`created_at`	number	任務建立時間（Unix 時間戳記，秒）。
`model`	string	執行此任務所使用的公開模型 ID。
`billing_status`	string	帳務狀態：reserved（已預扣）、charged（已扣款）、refunded（已退款）或 refund_failed（退款失敗）。
`credits`	number	為此任務預扣的額度。即使退款後此欄位仍會保留原數值；請檢查 billing_status 以確認最終扣款結果。
`failed_reason`	string \| null	任務失敗時的原因說明；成功時為 null。失敗的查詢回應中會省略 data 欄位。
`data`	object	僅在未失敗的任務查詢中出現。包含輸出成果與處理細節。
`data.results`	string[]	影片 URL 陣列。在生成完成前或影片過期後將為空陣列。
`data.video_expires_at`	string \| null	影片過期時間（ISO 8601 時間戳記）；在影片可用前為 null。請在此時間前下載保存結果。
`data.last_frame_url`	string \| null	若有請求且可用，則為最後影格的 URL；否則為 null。
`data.processing_time`	number \| null	服務商處理時長（秒，若可用）；否則為 null。

已完成任務：包含影片結果的查詢回應

當查詢狀態顯示 status=completed 時，代表影片已生成完畢。請從 data.results 取得影片網址，並於 data.video_expires_at 之前下載。billing_status=charged 表示已正式扣除預扣的額度。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

失敗任務：包含失敗原因與計費詳情的查詢回應

當查詢狀態顯示 status=failed 時，代表生成失敗。請參閱 failed_reason 瞭解失敗原因，並查看 billing_status 確認退款結果。在此範例中，refunded 表示額度已退還。credits 仍會顯示原先預扣的額度，且回應中不會包含 data 資料。

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

Webhook

在實際生產環境中整合時，請在建立任務時提供 callback_url。每個模型的參考指南中都包含回呼內容（Callback Payload）格式與接收端範例。

在建立任務的請求中設定 callback_url，即可在任務完成或失敗時接收 JSON POST 請求。您的伺服器必須在 15 秒內回傳 2xx 回應。發送失敗的回呼會進行重試；請根據任務 ID 進行等冪（Idempotent）處理，以防重複發送。

您的回呼端點必須接受含有 JSON 請求主體的 POST 請求 (Content-Type: application/json)。

建立包含回呼設定的任務

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Webhook 傳送的資料內容與任務查詢回應有所不同：它會省略 billing_status 和 credits；失敗詳情會放在 data.failed_reason 和 data.credits_refunded 中。Webhook 中的 created_at 為該事件建立時的 Unix 時間戳記（秒）。

任務完成：成功回呼的承載資料

產生成功時，回呼將包含 status=completed。請使用 id 識別任務，並透過 data.results 取得影片 URL。請務必在 data.video_expires_at 之前下載並儲存結果。

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

任務失敗：失敗回呼的承載資料

產生失敗時，回呼將包含 status=failed。請使用 id 識別任務，並透過 data.failed_reason 查看失敗原因，以及透過 data.credits_refunded 確認退回的點數。

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

接收端範例

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

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

此 Next.js 範例可讀取 JSON 回呼主體，並直接處理已完成與失敗的任務。請為您的應用程式加入持續性與任務 ID 去重功能；並在確認回呼前，將耗時較長的工作排入佇列。

錯誤處理

HTTP 錯誤會包含一個 error 物件，內有 code（錯誤碼）和 message（錯誤訊息）。即使任務成功建立，後續仍可能生成失敗；請持續查詢任務狀態或處理失敗回呼。

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	欄位	建議處理方法
400	`invalid_request`	請在重試前修正 JSON 格式、缺少的提示詞、無效的參數範圍或媒體 URL。
401	`invalid_api_key`	請檢查 Bearer 權杖（Token）以及 API 金鑰是否處於啟用狀態。
402	`insufficient_credits`	請儲值額度或降低任務成本。回應中可能會顯示所需的額度與目前可用額度。
403	`forbidden`	請檢查錯誤訊息中說明的帳戶權限限制。
404	`not_found`	請檢查任務 ID 是否正確，以及該金鑰是否屬於建立該任務的使用者。
429	`rate_limited`	請在 Retry-After 指定的間隔時間過後再重試。
500	`internal_error`	請檢查錯誤訊息和 API 日誌。請謹慎重試；重複送出建立請求可能會產生新的計費任務。