Official SDK quick start

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")

Integrate in four steps

1. Use the server-side OPENAIAV_API_KEY environment variable to call https://api.openaiav.com/v1/models and read current model keys, pricing and reference_modes.
2. POST prompt, referenceMode and referenceImages to /v1/generations. Reference images are public HTTPS URLs and need no pre-registration. Success is HTTP 201.
3. Save the returned id and poll the same GET /v1/generations/{id} after poll_after_ms. Keep waiting for processing, result_pending and submission_unknown; do not create another task.
4. After status becomes succeeded, download with GET /v1/generations/{id}/content. A full response is HTTP 200 and a single byte range is 206.

Authentication and idempotency

export OPENAIAV_API_KEY='oav_...'
export OPENAIAV_IDEMPOTENCY_KEY='openaiav-quickstart-4s-480p-001'

Send Authorization: Bearer oav_... on every request and keep the key server-side. Creation needs generation:create; polling and download need generation:read. Reuse the original Idempotency-Key after an uncertain network result; never pair one key with different bodies.

Request headers

Endpoints

Step 1: read model capabilities

Do not hard-code model capabilities. Submit only modes listed in reference_modes, and hide or block incompatible combinations before submission. The minimum example demonstrates a 4-second, 480p, no-audio request with seedance-2.5.

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

Minimum public video example

The sample contains the full flow: create → poll the same task → download. first_frame uses one reference image and adaptive; generateAudio=false avoids requesting audio. Success codes are 201, 200 and 200/206; on failure, inspect HTTP first and then 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'

Request parameters

Reference modes

first_frame

first_frame: the reference image becomes the opening frame and sets the composition. Submit exactly one referenceImages item; aspectRatio comes from the model's aspect_ratios, and locks to adaptive when the catalog offers it (output follows the reference image). first_last_frame: submit exactly 2 referenceImages — array order is first frame, then last frame — and the model fills in between. The two images need not share dimensions. Frame modes cannot be combined with 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: reference media locks subject, style and scene consistency without becoming the opening frame. Beyond referenceImages, capable models also accept referenceVideos and referenceAudios; per-type limits are in the table below, and any type the catalog does not declare is a 400 at submit time. Prompts address items by their order within each type: @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

One integration for every video model: same endpoint, same fields — switching models means changing model only. All differences are declared by the catalog, and the table below is that catalog: per model, which reference modes it supports and how much of each media type it accepts. Anything the catalog does not declare is rejected explicitly at submit time, never silently ignored.

First-frame details & last-frame relay

First-frame details: first_frame and omni_reference are mutually exclusive — one request picks exactly one. Under omni reference you may steer a reference image toward the opening shot via the prompt, but when strict first-frame fidelity matters, submit that image in first_frame mode. On Seedance 2.5, first-frame tasks fix the aspect ratio to adaptive (output follows the first frame). Last-frame relay: pass returnLastFrame: true at creation and a succeeded task also returns last_frame_url (a watermark-free PNG at video size, kept for 24 hours) — feed that URL directly as the next request’s first_frame referenceImages to chain multi-shot sequences, with no pre-registration step.

Polling and download

Only succeeded and failed are terminal. submission_unknown is a reconciliation state: retain the original task ID, keep polling, and never replay creation. After success, use the authenticated /content path rather than relying on any non-Open AIav location. Results are kept for 24 hours (the detail response carries output_expires_at; expired downloads return 410 OUTPUT_EXPIRED, so save promptly).

Retired endpoint migration

Error code reference

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