官方 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。

仅在控制台返回的错误码