Official SDK quick start

The official SDKs wrap the whole flow (create → poll → download) with automatic idempotency keys and typed errors. The Node SDK has no dependencies; the Python SDK depends only on httpx. They are distributed as GitHub repositories for now; npm and PyPI releases will be announced separately.

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

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_...'
# 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)"

Send Authorization: Bearer oav_... on every request and keep the key server-side. Creation needs generation:create; polling and download need generation:read. Generate a new Idempotency-Key (a UUID) for each create intent, so every run of a sample gets a new key; reuse it only when retrying that same create after an uncertain network result, and 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-oa.

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 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'

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-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: 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-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"
}

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, so 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.

Reference video pricing

• Reference videos with a measurable duration are billed at a fixed price, which you can preview first. If the duration cannot be measured, the preview is rejected without a charge.
• Call POST /v1/generation-quotes to preview the current price. URL videos are measured again and repriced at creation; the creation response reserved_usd gives the actual amount. You may still send quoteId, but it does not lock the price. expires_at only suggests when to refresh the preview.
• The model catalog sets per-video and total duration, count and minimum billable seconds. Each reference video must be 2–15 seconds for the Seedance 2.0 series and 2–30 seconds for other supported models. Measured input outside the model limits returns 422 REFERENCE_DURATION_OUT_OF_RANGE without a charge.
• Use a public HTTPS direct link to MP4/MOV. Known files above 200 MiB return REFERENCE_VIDEO_TOO_LARGE; an unstated size can still be quoted. Private URLs return REFERENCE_URL_NOT_PUBLIC, and busy probes return 429 REFERENCE_PROBE_BUSY. Console uploads are limited to 32 MiB.
• Every task is charged its quoted price, reserved_usd, at creation; on success that is the final charge, and on failure it is refunded in full. A preview's price_usd equals what creation would charge at that moment; output duration must still be explicit, not -1.
• Public video URLs are probed for the preview and again at creation, then passed directly to the generation service without platform storage or asset registration. Keep the URL content stable. Uploads use a separate registered-asset path. Model restrictions on real human faces still apply.

Image model pricing

• Image models are priced per image by resolution and aspectRatio (image_pricing.rates). For the gpt-image-* and nano-banana-* models, these listed prices are for a short prompt with no reference images.
• Reference images and longer prompts raise the charge for these models. Before you create a task, call POST /v1/generation-quotes with the same body: price_usd is the charge for that request at current prices. A failed task is refunded in full.

Polling and download

Only succeeded and failed are terminal. submission_unknown means acceptance is still being confirmed and result_pending is finalizing: 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.

Image task failure codes

When an image task ends with status=failed, read error_code and match it below. A failed task is refunded in full. The SDKs raise GenerationFailedError with the same code.

Codes returned only in the console