Schnellstart mit den offiziellen SDKs

Die offiziellen SDKs bündeln den gesamten Ablauf (Erstellen → Abfragen → Herunterladen) mit automatischen Idempotenzschlüsseln und typisierten Fehlern. Das Node-SDK hat keine Abhängigkeiten, das Python-SDK hängt nur von httpx ab. Sie werden vorerst als GitHub-Repositorys bereitgestellt; Veröffentlichungen auf npm und PyPI werden gesondert angekündigt.

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

In vier Schritten integrieren

1. Rufen Sie mit der serverseitigen Umgebungsvariable OPENAIAV_API_KEY https://api.openaiav.com/v1/models auf und lesen Sie die aktuellen Modellschlüssel, Preise und reference_modes.
2. Senden Sie prompt, referenceMode und referenceImages per POST an /v1/generations. Referenzbilder sind öffentliche HTTPS-URLs und müssen nicht vorab registriert werden. Erfolg ist HTTP 201.
3. Speichern Sie die zurückgegebene id und fragen Sie nach poll_after_ms dieselbe GET /v1/generations/{id} ab. Bei processing, result_pending und submission_unknown warten Sie weiter; erstellen Sie keine neue Aufgabe.
4. Sobald der Status succeeded ist, laden Sie mit GET /v1/generations/{id}/content herunter. Eine vollständige Antwort ist HTTP 200, ein einzelner Byte-Bereich 206.

Authentifizierung und Idempotenz

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

Senden Sie bei jeder Anfrage Authorization: Bearer oav_... und bewahren Sie den Schlüssel serverseitig auf. Das Erstellen erfordert generation:create, Abfragen und Download erfordern generation:read. Generieren Sie für jede Erstellungsabsicht einen neuen Idempotency-Key (eine UUID), sodass jeder Lauf eines Beispiels einen neuen Schlüssel erhält. Verwenden Sie ihn nur erneut, wenn Sie genau diese Erstellung nach einem unklaren Netzwerkergebnis wiederholen; kombinieren Sie einen Schlüssel nie mit unterschiedlichen Inhalten.

Anfrage-Header

Endpunkte

Schritt 1: Modellfunktionen abrufen

Legen Sie Modellfunktionen nicht fest im Code fest. Senden Sie nur Modi, die in reference_modes aufgeführt sind, und blenden Sie inkompatible Kombinationen vor dem Absenden aus oder sperren Sie sie. Das minimale Beispiel zeigt eine Anfrage mit 4 Sekunden, 480p und ohne Audio mit seedance-2.5-oa.

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

Minimales öffentliches Videobeispiel

Das Beispiel enthält den gesamten Ablauf: Erstellen → dieselbe Aufgabe abfragen → Herunterladen. first_frame verwendet ein Referenzbild und adaptive; generateAudio=false verzichtet auf Audio. Die Erfolgscodes sind 201, 200 und 200/206; prüfen Sie bei Fehlern zuerst HTTP und dann 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'

Anfrageparameter

Referenzmodi

first_frame

first_frame: Das Referenzbild wird zum ersten Bild und bestimmt den Bildaufbau. Senden Sie genau einen Eintrag in referenceImages; aspectRatio stammt aus den aspect_ratios des Modells und ist auf adaptive festgelegt, wenn der Katalog es anbietet (die Ausgabe folgt dem Referenzbild). first_last_frame: Senden Sie genau 2 referenceImages. Die Reihenfolge im Array ist Startbild, dann Endbild, und das Modell ergänzt den Übergang. Die beiden Bilder müssen nicht gleich groß sein. Bildmodi lassen sich nicht mit omni_reference kombinieren.

{
  "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: Referenzmedien halten Motiv, Stil und Szene konsistent, ohne zum ersten Bild zu werden. Neben referenceImages akzeptieren geeignete Modelle auch referenceVideos und referenceAudios; die Limits je Typ stehen in der Tabelle unten, und jeder Typ, den der Katalog nicht deklariert, führt beim Absenden zu 400. Prompts sprechen Elemente in ihrer Reihenfolge innerhalb des Typs an: @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"
}

Aktuelle Kompatibilität

Eine Integration für alle Videomodelle: derselbe Endpunkt, dieselben Felder. Um das Modell zu wechseln, ändern Sie nur model. Alle Unterschiede deklariert der Katalog, und die Tabelle unten ist dieser Katalog: pro Modell, welche Referenzmodi es unterstützt und wie viele Medien jedes Typs es akzeptiert. Alles, was der Katalog nicht deklariert, wird beim Absenden ausdrücklich abgelehnt und nie stillschweigend ignoriert.

Details zum Startbild und Weitergabe des Endbilds

Details zum Startbild: first_frame und omni_reference schließen sich aus; eine Anfrage wählt genau einen Modus. Bei der Omni-Referenz können Sie ein Referenzbild per Prompt in Richtung Eröffnungsbild lenken; wenn es genau dem Startbild entsprechen muss, senden Sie dieses Bild im Modus first_frame. Bei Seedance 2.5 ist das Seitenverhältnis von Startbild-Aufgaben auf adaptive festgelegt (die Ausgabe folgt dem Startbild). Endbild weitergeben: Übergeben Sie beim Erstellen returnLastFrame: true, dann liefert eine erfolgreiche Aufgabe zusätzlich last_frame_url (ein PNG ohne Wasserzeichen in Videogröße, 24 Stunden aufbewahrt). Übergeben Sie diese URL direkt als referenceImages für first_frame der nächsten Anfrage, um mehrere Einstellungen ohne Vorabregistrierung aneinanderzureihen.

Preise für Referenzvideos

• Referenzvideos mit messbarer Dauer werden zum Festpreis abgerechnet, den Sie vorab in einer Vorschau sehen können. Ist die Dauer nicht messbar, wird die Vorschau ohne Belastung abgelehnt.
• Rufen Sie POST /v1/generation-quotes für eine Preisvorschau auf. URL-Videos werden beim Erstellen erneut gemessen und bepreist; reserved_usd der Erstellungsantwort ist der tatsächliche Betrag. quoteId bindet den Preis nicht, expires_at empfiehlt nur die Aktualisierung.
• Der Modellkatalog legt Dauer pro Video und insgesamt, Anzahl und Mindestabrechnungszeit fest. Jedes Referenzvideo muss bei der Seedance-2.0-Reihe 2–15 Sekunden und bei anderen unterstützten Modellen 2–30 Sekunden lang sein. Gemessene Eingaben außerhalb der Grenzen liefern ohne Belastung 422 REFERENCE_DURATION_OUT_OF_RANGE.
• Verwenden Sie einen öffentlichen HTTPS-Direktlink zu MP4/MOV. Bekannte Dateien über 200 MiB liefern REFERENCE_VIDEO_TOO_LARGE; auch ohne Größenangabe ist ein Angebot möglich. Private URLs liefern REFERENCE_URL_NOT_PUBLIC, ausgelastete Prüfungen 429 REFERENCE_PROBE_BUSY. Für Uploads in der Konsole gilt 32 MiB.
• Bei jeder Aufgabe wird beim Erstellen ihr Festpreis reserved_usd berechnet; bei Erfolg bleibt es bei genau diesem Betrag, bei Fehlschlag wird er vollständig erstattet. price_usd einer Vorschau entspricht dem, was das Erstellen in diesem Moment kosten würde; geben Sie eine Ausgabedauer statt -1 an.
• Öffentliche Video-URLs werden für die Vorschau und beim Erstellen geprüft und danach ohne Speicherung oder Asset-Registrierung direkt übergeben. Halten Sie den Inhalt stabil. Uploads nutzen einen separaten Weg; Beschränkungen für echte Gesichter gelten weiter.

Preise für Bildmodelle

• Bildmodelle werden pro Bild nach resolution und aspectRatio abgerechnet (image_pricing.rates). Bei den Modellen gpt-image-* und nano-banana-* gelten die angezeigten Preise für einen kurzen Prompt ohne Referenzbilder.
• Bei diesen Modellen erhöhen Referenzbilder und längere Prompts den Betrag. Rufen Sie vor dem Erstellen einer Aufgabe POST /v1/generation-quotes mit demselben Body auf: price_usd ist der Betrag für diese Anfrage zu aktuellen Preisen. Fehlgeschlagene Aufgaben werden vollständig erstattet.

Polling und Download

Nur succeeded und failed sind Endzustände. Bei submission_unknown wird die Annahme noch bestätigt, result_pending wird abgeschlossen: Behalten Sie die ursprüngliche Aufgaben-ID, fragen Sie weiter ab und wiederholen Sie die Erstellung nie. Verwenden Sie nach Erfolg den authentifizierten Pfad /content statt Adressen außerhalb von Open AIav. Ergebnisse werden 24 Stunden aufbewahrt (die Detailantwort enthält output_expires_at; abgelaufene Downloads liefern 410 OUTPUT_EXPIRED, speichern Sie also rechtzeitig).

Migration eingestellter Endpunkte

Fehlercodes

Vollständige Übersicht: HTTP-Status, Code, Bedeutung, empfohlene Maßnahme und SDK-Fehlerklasse. Diese Tabelle nutzt dieselbe Datenquelle wie die Fehlerzuordnung der SDKs; unbekannte neue Codes behandelt das SDK nach HTTP-Status.

Fehlercodes fehlgeschlagener Bildaufgaben

Endet eine Bildaufgabe mit status=failed, lesen Sie error_code und gleichen Sie den Code mit der Tabelle ab. Fehlgeschlagene Aufgaben werden vollständig erstattet. Die SDKs lösen GenerationFailedError mit demselben Code aus.

Codes, die nur in der Konsole zurückgegeben werden