# Seedance 2.0 V2 影片 API

# Seedance 2.0 V2 影片 API

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

## 端點與驗證

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

| 操作 | 方法與位址 |
| --- | --- |
| 查看可用模型 | `GET https://u9ai.ai/v1/models` |
| 建立 Mini 任務 | `POST https://u9ai.ai/api/v2/open/aigc/seedance2-0-mini-oversea` |
| 建立 Fast 任務 | `POST https://u9ai.ai/api/v2/open/aigc/seedance2-0-fast-oversea` |
| 查詢單一任務 | `GET https://u9ai.ai/api/v2/open/aigc/{taskId}` |
| 批次查詢任務 | `POST https://u9ai.ai/api/v2/open/aigc/batch` |
| 查詢餘額 / 請求紀錄 | `GET https://u9ai.ai/api/v2/open/balance` / `GET https://u9ai.ai/api/v2/open/records` |

請勿把上游 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」說明用途。

```bash
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 時，標記為「提交結果未知」，停止自動重複建立，先透過請求紀錄或人工排查確認是否已產生任務與費用。

## 查詢、下載與失敗處理

```bash
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、原始素材或付款資料。