官方 SDK 快速上手

The official SDKs wrap the one-step contract (create → poll → download) with automatic idempotency keys and typed errors; the Node SDK has zero dependencies and Python depends only on httpx. Distributed as GitHub repositories for now — npm/PyPI releases will be announced separately.

Node

npm install github:openaiav/sdk-node   # npm 正式发布另行公告

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 正式发布另行公告

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_...'
export OPENAIAV_IDEMPOTENCY_KEY='openaiav-quickstart-4s-480p-001'

每個請求都帶 Authorization: Bearer oav_...。金鑰只放在服務端。建立任務需要 generation:create，查詢和下載需要 generation:read。網路結果不確定時複用原 Idempotency-Key；同一個鍵不得配不同請求體。

Request headers

端點一覽

第一步：讀取模型能力

不要寫死模型能力。只有 reference_modes 列出的模式可以提交；介面也應在提交前隱藏或攔截不相容組合。最小示例固定演示 seedance-2.5 的 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 both values in environment variables; do not paste secrets into shell history.
# Generate OPENAIAV_IDEMPOTENCY_KEY once for this create intent and keep it unchanged on every retry.
# Set it before the first create, then reuse the exact value after a lost response.
# 1. Create — success: HTTP 201. On failure, the response body contains error.code.
curl --fail-with-body --request POST 'https://api.openaiav.com/v1/generations' \
  --header "Authorization: Bearer $OPENAIAV_API_KEY" \
  --header "Idempotency-Key: $OPENAIAV_IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "女孩写完一封信，从乡间石屋走入清晨阳光",
  "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",
  "prompt": "女孩写完一封信，从乡间石屋走入清晨阳光",
  "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",
  "prompt": "@Image1 保持人物身份与服装一致，女孩从乡间石屋走入清晨阳光",
  "resolution": "480p",
  "aspectRatio": "16:9",
  "durationSeconds": 4,
  "referenceMode": "omni_reference",
  "referenceImages": [
    "https://developers.openaiav.com/samples/seedance-letter-reference.webp"
  ],
  "generateAudio": false,
  "outputFormat": "mp4"
}

Live compatibility

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

First-frame details & last-frame relay

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

輪詢與下載

succeeded 與 failed 才是終態。submission_unknown 是待對賬狀態：保留原任務 ID，繼續輪詢，絕不能重放建立請求。成功後優先使用鑑權下載路徑 /content，不要依賴任何非 Open AIav 地址。產物保留 24 小時(詳情返回 output_expires_at 倒計時;過期後下載返回 410 OUTPUT_EXPIRED,請及時轉存)。

舊端點遷移

錯誤碼對照

Full reference: HTTP status, code, meaning, suggested handling, and the SDK error class. This table shares its data source with the SDK error map; unknown new codes fall back by HTTP status in the SDK.

Console-session-only codes