官方 SDK 快速上手

官方 SDK 封装一步式契约(提交 → 轮询 → 下载),自动幂等键与类型化错误;Node 零依赖,Python 仅依赖 httpx。当前为 GitHub 仓库形态,npm/PyPI 正式发布另行公告。

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；同一个键不得配不同请求体。

请求头

端点一览

第一步：读取模型能力

不要写死模型能力。只有 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"
}

真实兼容范围

接入方式对所有视频模型是同一套：同一个端点、同一组字段，换模型只改 model。差异全部由目录声明——下表就是目录本身，逐个模型列出它支持哪些参考模式、各类素材收几个。目录没声明的能力，提交时会被明确拒绝，不会静默忽略。

首帧细则与尾帧接力

首帧细则: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,请及时转存)。

旧端点迁移

错误码对照

完整对照:HTTP 状态、错误码、含义、建议处置与 SDK 错误类。本表与 SDK 的错误映射同一数据源,未知新码由 SDK 按 HTTP 状态段兜底。

控制台会话面专属码