U9 AI · DOCUMENTATION

Seedance 2.0 V2 影片 API

使用公開 API 建立、查詢及下載 Seedance Mini 或 Fast V2 影片任務。

# Seedance 2.0 V2 影片 API

本文是 U9AI 目前公開的 Seedance 2.0 Mini / Fast V2 影片任務契約。它使用 U9AI API 金鑰，不使用供應商金鑰、瀏覽器 Cookie 或網站登入工作階段。V2 是非同步協定：建立成功只代表任務已受理，不代表影片已完成。

端點與驗證#

所有請求使用 HTTPS，並帶上 Authorization: Bearer $U9AI_API_KEY。先查詢模型目錄，以確認金鑰本次可驗證；模型是否對該金鑰開放仍以實際回傳為準。

請勿把上游 V3 的 /api/v3/... 路徑或 generate_audio 欄位混入這個 V2 請求。U9AI 目前 Seedance V2 的音軌欄位是 camelCase：generateAudio。

建立任務#

content 必須是陣列，並至少包含一個 type: "text" 的提示詞項。Mini 和 Fast 支援 480p、720p；時長為 4–15 秒。常用比例為 16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive。

參考素材使用服務端可讀取的完整 HTTPS URL，或完整 data:image/...;base64,... URI；請勿傳送本機檔案路徑、私網 URL 或需要瀏覽器登入的連結。圖片可用 first_frame、last_frame 或 reference_image 角色。同一張圖不可同時作為首幀和尾幀；多圖參考請在提示詞中按「圖片1」「圖片2」說明用途。

curl --fail-with-body -sS "https://u9ai.ai/api/v2/open/aigc/seedance2-0-mini-oversea" \
  -H "Authorization: Bearer $U9AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {"type":"text","text":"以圖片1為參考，生成自然鏡頭運動的短影片。"},
      {"type":"image_url","image_url":{"url":"https://example.com/your-authorized-image.jpg"},"role":"reference_image"}
    ],
    "ratio":"9:16",
    "duration":5,
    "resolution":"720p",
    "generateAudio":true
  }'

將路徑中的 mini 改為 fast 即可建立 Fast 任務。僅在希望無聲成片時設定 generateAudio: false；生成音軌不保證逐字旁白、字幕或特定配樂，成片仍需驗收。

建立回應應同時滿足 HTTP 成功、沒有業務錯誤且有非空 data.taskId。立即保存 data.taskId、U9AI 回傳的 X-Request-ID 和時間；請勿把 API 金鑰寫入日誌。逾時、5xx 或回應缺少 task ID 時，標記為「提交結果未知」，停止自動重複建立，先透過請求紀錄或人工排查確認是否已產生任務與費用。

查詢、下載與失敗處理#

curl --fail-with-body -sS \
  -H "Authorization: Bearer $U9AI_API_KEY" \
  "https://u9ai.ai/api/v2/open/aigc/YOUR_TASK_ID"

V2 任務常見狀態為 processing、success、failed。success 時從 data.result 的 URL 陣列取得成片；failed 時讀取 data.errorMsg。請依帳戶限額處理 429 與 Retry-After，建議先採單並發並漸進輪詢。下載 data.result 時不要向結果檔案網域傳送 API 金鑰；確認 HTTP 狀態、非空檔案、可播放的影片串流與音軌後，才向終端使用者展示。

建立任務會消耗餘額。開始前設定單一任務和總任務預算，完成後以 U9AI 請求紀錄和錢包流水為準。GET /v1/models 成功只表示驗證和模型目錄查詢成功，不代表影片生成已完成。

移交排障資訊#

需要技術支援時，請提供時間（含時區）、模型、HTTP 狀態、X-Request-ID、CF-Ray（如有）、業務錯誤碼、taskId、最終狀態與 data.errorMsg。請勿提供 API 金鑰、Authorization 請求頭、Cookie、私人素材 URL、原始素材或付款資料。