官方 SDK 快速入門

官方 SDK 封裝了完整流程（建立 → 輪詢 → 下載），會自動產生冪等鍵並提供類型化錯誤；Node SDK 沒有任何相依套件，Python SDK 只相依 httpx。目前以 GitHub 儲存庫形式提供，npm / PyPI 正式發布將另行公告。

Node

npm install github:openaiav/sdk-node   # npm release to be announced

import { OpenAiav } from '@openaiav/sdk'
const client = new OpenAiav({ apiKey: process.env.OPENAIAV_API_KEY })
const task = await client.generations.createAndWait({
  model: 'seedance-2.5-oa', prompt: 'She walks into the sunlight.',
  resolution: '480p', aspectRatio: 'adaptive', durationSeconds: 4,
  generateAudio: false
})
await client.generations.downloadToFile(task.id, './out.mp4')

Python

pip install git+https://github.com/openaiav/sdk-python   # PyPI release to be announced

from openaiav import OpenAiav
client = OpenAiav(os.environ["OPENAIAV_API_KEY"])
task = client.generations.create_and_wait({
    "model": "seedance-2.5-oa", "prompt": "She walks into the sunlight.",
    "resolution": "480p", "aspectRatio": "adaptive", "durationSeconds": 4,
    "generateAudio": False,
})
client.generations.download_to_file(task["id"], "./out.mp4")

四步完成串接

1. 使用伺服器端環境變數 OPENAIAV_API_KEY 呼叫 https://api.openaiav.com/v1/models，讀取目前的模型鍵、計價與 reference_modes。
2. 向 POST /v1/generations 提交 prompt、referenceMode 與 referenceImages；參考圖是公開的 HTTPS URL，不需要預先註冊。建立成功時回傳 HTTP 201。
3. 儲存回應中的 id，依 poll_after_ms 對同一個 GET /v1/generations/{id} 輪詢。processing、result_pending、submission_unknown 都請繼續等待，不要重新建立。
4. 狀態變為 succeeded 後，呼叫 GET /v1/generations/{id}/content 下載；完整回應為 HTTP 200，單一區間的 Range 為 206。

驗證與冪等

export OPENAIAV_API_KEY='oav_...'
# One Idempotency-Key per create intent: every run of this script makes a new one.
# Reuse it only when retrying this same create. No uuidgen? IDEMPOTENCY_KEY=$(python3 -c 'import uuid;print(uuid.uuid4())')
IDEMPOTENCY_KEY=$(uuidgen | tr 'A-Z' 'a-z')
echo "Idempotency-Key: $IDEMPOTENCY_KEY  (reuse this value only when retrying this same create)"

每個請求都要帶 Authorization: Bearer oav_...，金鑰只放在伺服器端。建立任務需要 generation:create，查詢和下載需要 generation:read。每個建立意圖生成一個新的 Idempotency-Key（UUID），範例每次執行都會換新的鍵；只在網路結果不確定、重試同一個建立請求時重複使用它，同一個鍵不得搭配不同的請求內容。

請求標頭

端點一覽

第一步：讀取模型能力

不要把模型能力寫死。只有 reference_modes 列出的模式可以提交；介面也應在提交前隱藏或阻擋不相容的組合。最小範例固定示範 seedance-2.5-oa 的 4 秒、480p、無音訊請求。

curl --fail-with-body 'https://api.openaiav.com/v1/models' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY"

最小公開影片範例

完整流程都在同一個範例裡：建立 → 輪詢同一任務 → 下載。 first_frame 使用一張參考圖和 adaptive；generateAudio=false 避免請求音訊。建立、輪詢、下載的成功狀態分別是 201、200、200/206；失敗回應先讀取 HTTP，再讀取 error.code。

# Keep OPENAIAV_API_KEY in an environment variable; do not paste secrets into shell history.
# One Idempotency-Key per create intent: every run of this script makes a new one.
# Reuse it only when retrying this same create. No uuidgen? IDEMPOTENCY_KEY=$(python3 -c 'import uuid;print(uuid.uuid4())')
IDEMPOTENCY_KEY=$(uuidgen | tr 'A-Z' 'a-z')
echo "Idempotency-Key: $IDEMPOTENCY_KEY  (reuse this value only when retrying this same create)"

# 1. Create — success: HTTP 201. On failure, the response body contains error.code.
# Lost response (timeout or dropped connection)? Re-run this same command in this shell:
# the unchanged $IDEMPOTENCY_KEY returns the original task instead of creating a second one.
curl --fail-with-body --request POST 'https://api.openaiav.com/v1/generations' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5-oa",
  "prompt": "A young woman finishes a letter and walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "adaptive",
  "durationSeconds": 4,
  "referenceMode": "first_frame",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}'

# 2. Save the returned id as TASK_ID. Poll the same id — success: HTTP 200.
curl --fail-with-body 'https://api.openaiav.com/v1/generations/TASK_ID' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY"

# Repeat step 2 after poll_after_ms until status is succeeded or failed.
# Never recreate a task whose status is submission_unknown.

# 3. After succeeded, download — success: HTTP 200 (or 206 with Range).
curl --fail-with-body --location 'https://api.openaiav.com/v1/generations/TASK_ID/content' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --output 'result.mp4'

請求參數

參考素材模式

first_frame

first_frame：參考圖會成為起始畫面並決定構圖。必須且只能提交 1 張 referenceImages；aspectRatio 取自所選模型的 aspect_ratios，目錄含 adaptive 時會固定為 adaptive（輸出依參考圖畫幅）。 first_last_frame：提交剛好 2 張 referenceImages，依陣列順序分別是首幀與尾幀，中間畫面由模型補全。兩張圖不需要相同尺寸。幀模式與 omni_reference 互斥。

{
  "model": "seedance-2.5-oa",
  "prompt": "A young woman finishes a letter and walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "adaptive",
  "durationSeconds": 4,
  "referenceMode": "first_frame",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

omni_reference

omni_reference：參考素材用於鎖定主體、風格與場景的一致性，不要求成為首幀。除 referenceImages 外，支援的模型還可傳入 referenceVideos 與 referenceAudios；各類上限請見下表，目錄未宣告的類型一提交即回傳 400。提示詞依同類型內的陣列順序引用 @Image1、@Video1、@Audio1。

{
  "model": "seedance-2.5-oa",
  "prompt": "Keep the identity and outfit from @Image1; a young woman walks from a stone cottage into the morning sunlight",
  "resolution": "480p",
  "aspectRatio": "16:9",
  "durationSeconds": 4,
  "referenceMode": "omni_reference",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

實際相容範圍

所有影片模型都使用同一套串接方式：同一個端點、同一組欄位，換模型只需改 model。差異全部由目錄宣告——下表就是目錄本身，逐一列出每個模型支援哪些參考模式、各類素材可收幾個。目錄沒有宣告的能力，提交時會被明確拒絕，不會默默忽略。

首幀細則與尾幀接力

首幀細則：first_frame 與 omni_reference 互斥，同一請求只能選其一；omni 模式下可用提示詞間接引導某張參考圖作為起始畫面，但需要嚴格的首幀一致時，請使用 first_frame 模式提交那張圖。Seedance 2.5 的首幀任務畫幅固定為 adaptive（輸出依首幀）。尾幀接力：建立時傳入 returnLastFrame: true，成功後任務會另外回傳 last_frame_url（與影片同寬高的無浮水印 PNG，保留 24 小時）——把這個 URL 直接作為下一個請求 first_frame 的 referenceImages，即可串聯多鏡頭的連續敘事，不需任何預先註冊步驟。

參考影片計價

• 可測得時長的參考影片按固定價格計費，可先預覽這個金額；無法測得時長時拒絕預覽，不扣費。
• 呼叫 POST /v1/generation-quotes 預覽目前價格。伺服器會測量 URL 影片；建立任務時重新測量並定價，實際金額以建立回應的 reserved_usd 為準。仍可傳入 quoteId，但不鎖定價格；expires_at 僅提示重新整理預覽。
• 模型目錄規定單一、總時長、數量及最低計費秒數；Seedance 2.0 系列的每段參考影片為 2–15 秒，其他適用模型為 2–30 秒。實測超出範圍回傳 422 REFERENCE_DURATION_OUT_OF_RANGE，不扣費。
• 只支援 MP4/MOV 公開 HTTPS 直連網址。已知檔案大小超過 200 MiB 時回傳 REFERENCE_VIDEO_TOO_LARGE；未回報大小仍可報價。非公開位址回傳 REFERENCE_URL_NOT_PUBLIC，探測繁忙時回傳 429 REFERENCE_PROBE_BUSY。控制台上傳上限為 32 MiB。
• 每個任務都在建立時依報價扣除 reserved_usd，成功時就按這個金額，失敗時全額退回。預覽中的 price_usd 等於在預覽那一刻建立所需扣除的金額；輸出影片長度仍須明確指定，不可使用 -1。
• 公開影片 URL 在預覽和建立時各探測一次，隨後以直連網址供生成服務讀取，無須平台儲存或素材註冊。請保持連結內容穩定。上傳檔案走獨立註冊路徑。真人臉素材仍受模型限制。

圖片模型計價

• 圖片模型按張計價，價格隨 resolution 與 aspectRatio 變化，請見 image_pricing.rates。gpt-image-* 與 nano-banana-* 模型的列表價以短提示詞、不帶參考圖計算。
• 帶參考圖或提示詞較長時，這些模型的扣款會更高。建立任務前，用同樣的請求內容呼叫 POST /v1/generation-quotes，回傳的 price_usd 就是這次請求按目前價格的扣款金額。任務失敗將全額退款。

輪詢與下載

只有 succeeded 與 failed 是終態。submission_unknown 表示受理結果確認中，result_pending 表示結果正在完成：保留原任務 ID，繼續輪詢，絕對不要重送建立請求。成功後請優先使用需驗證的下載路徑 /content，不要依賴任何非 Open AIav 的網址。輸出結果保留 24 小時（詳細資訊會回傳 output_expires_at 倒數；過期後下載會回傳 410 OUTPUT_EXPIRED，請及時另存）。

舊端點遷移

錯誤碼對照

完整對照：HTTP 狀態、錯誤碼、含義、建議處理方式與 SDK 錯誤類別。本表與 SDK 的錯誤對應使用同一個資料來源；遇到未知的新錯誤碼時，SDK 會依 HTTP 狀態分類處理。

圖片任務失敗碼

圖片任務以 status=failed 結束時，請讀取 error_code 並對照下表。失敗的任務將全額退款。SDK 會拋出帶有同一錯誤碼的 GenerationFailedError。

僅在控制台回傳的錯誤碼