Démarrage rapide avec les SDK officiels

Les SDK officiels encapsulent tout le parcours (création → polling → téléchargement) avec des clés d’idempotence automatiques et des erreurs typées. Le SDK Node n’a aucune dépendance ; le SDK Python dépend uniquement de httpx. Ils sont pour l’instant distribués sous forme de dépôts GitHub ; les publications sur npm et PyPI seront annoncées séparément.

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

Intégration en quatre étapes

1. Utilisez la variable d’environnement OPENAIAV_API_KEY côté serveur pour appeler https://api.openaiav.com/v1/models et lire les clés de modèle, les tarifs et les reference_modes actuels.
2. Envoyez prompt, referenceMode et referenceImages en POST à /v1/generations. Les images de référence sont des URL HTTPS publiques et ne nécessitent aucun préenregistrement. La réussite renvoie HTTP 201.
3. Enregistrez l’id renvoyé et interrogez le même GET /v1/generations/{id} après poll_after_ms. Continuez d’attendre pour processing, result_pending et submission_unknown ; ne créez pas d’autre tâche.
4. Une fois le statut succeeded, téléchargez avec GET /v1/generations/{id}/content. Une réponse complète renvoie HTTP 200 et une plage d’octets unique 206.

Authentification et idempotence

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

Envoyez Authorization: Bearer oav_... à chaque requête et conservez la clé côté serveur. La création requiert generation:create ; le polling et le téléchargement requièrent generation:read. Générez une nouvelle Idempotency-Key (un UUID) pour chaque intention de création, afin que chaque exécution d’un exemple obtienne une nouvelle clé ; ne la réutilisez que pour relancer cette même création après un résultat réseau incertain, et n’associez jamais une même clé à des corps différents.

En-têtes de requête

Endpoints

Étape 1 : lire les fonctionnalités des modèles

Ne codez pas en dur les fonctionnalités des modèles. N’envoyez que les modes listés dans reference_modes, et masquez ou bloquez les combinaisons incompatibles avant l’envoi. L’exemple minimal montre une requête de 4 secondes en 480p, sans audio, avec seedance-2.5-oa.

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

Exemple vidéo public minimal

L’exemple contient tout le parcours : création → polling de la même tâche → téléchargement. first_frame utilise une image de référence et adaptive ; generateAudio=false évite de demander de l’audio. Les codes de réussite sont 201, 200 et 200/206 ; en cas d’échec, examinez d’abord le code HTTP, puis 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'

Paramètres de la requête

Modes de référence

first_frame

first_frame : l’image de référence devient la première image et fixe la composition. Envoyez exactement un élément dans referenceImages ; aspectRatio provient des aspect_ratios du modèle et est fixé à adaptive lorsque le catalogue le propose (le résultat suit l’image de référence). first_last_frame : envoyez exactement 2 referenceImages. L’ordre du tableau est la première image, puis la dernière, et le modèle génère l’intervalle. Les deux images n’ont pas besoin d’avoir les mêmes dimensions. Les modes d’image ne peuvent pas être combinés avec 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 : les médias de référence assurent la cohérence du sujet, du style et de la scène sans devenir la première image. En plus de referenceImages, les modèles compatibles acceptent aussi referenceVideos et referenceAudios ; les limites par type figurent dans le tableau ci-dessous, et tout type non déclaré par le catalogue renvoie une erreur 400 à l’envoi. Les prompts désignent les éléments selon leur ordre dans chaque 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"
}

Compatibilité actuelle

Une seule intégration pour tous les modèles vidéo : même endpoint, mêmes champs. Changer de modèle revient à modifier model uniquement. Toutes les différences sont déclarées par le catalogue, et le tableau ci-dessous est ce catalogue : pour chaque modèle, les modes de référence pris en charge et la quantité acceptée pour chaque type de média. Tout ce que le catalogue ne déclare pas est refusé explicitement à l’envoi, jamais ignoré en silence.

Détails sur la première image et relais de la dernière image

Détails sur la première image : first_frame et omni_reference s’excluent mutuellement, une requête en choisit donc un seul. Avec la référence omni, vous pouvez orienter une image de référence vers le plan d’ouverture via le prompt ; mais si la première image doit être strictement identique, envoyez cette image en mode first_frame. Sur Seedance 2.5, les tâches avec première image fixent le format d’image à adaptive (le résultat suit la première image). Relais de la dernière image : passez returnLastFrame: true à la création, et une tâche réussie renvoie aussi last_frame_url (un PNG sans filigrane à la taille de la vidéo, conservé 24 heures). Utilisez directement cette URL comme referenceImages du first_frame de la requête suivante pour enchaîner plusieurs plans, sans étape de préenregistrement.

Tarification des vidéos de référence

• Les vidéos de référence dont la durée est mesurable sont facturées à prix fixe, que vous pouvez prévisualiser d’abord. Si leur durée ne peut pas être mesurée, la prévisualisation est refusée sans frais.
• Appelez POST /v1/generation-quotes pour voir le prix actuel. Les vidéos URL sont remesurées et revalorisées à la création ; le reserved_usd de la réponse est le montant réel. quoteId ne bloque pas le prix et expires_at suggère seulement une actualisation.
• Le catalogue fixe les durées par vidéo et au total, le nombre de vidéos et la durée minimale facturable. Chaque vidéo de référence doit durer de 2 à 15 secondes pour la série Seedance 2.0 et de 2 à 30 secondes pour les autres modèles compatibles. Une durée mesurée hors limites renvoie 422 REFERENCE_DURATION_OUT_OF_RANGE sans frais.
• Utilisez un lien direct HTTPS public vers un MP4/MOV. Une taille connue supérieure à 200 MiB renvoie REFERENCE_VIDEO_TOO_LARGE ; une taille inconnue peut être chiffrée. Les URL privées renvoient REFERENCE_URL_NOT_PUBLIC et les sondes occupées 429 REFERENCE_PROBE_BUSY. Les téléversements console sont limités à 32 MiB.
• Pour chaque tâche, le prix de son devis, reserved_usd, est débité à la création ; en cas de réussite, ce montant est définitif, et en cas d’échec il est intégralement remboursé. Le price_usd d’une prévisualisation correspond à ce que coûterait la création à ce moment-là ; précisez la durée, sans -1.
• Les URL publiques de vidéo sont vérifiées pour la prévisualisation puis à la création, avant d'être transmises directement sans stockage ni enregistrement. Gardez leur contenu stable. Les téléversements suivent une autre voie ; les restrictions relatives aux visages réels restent applicables.

Tarifs des modèles d’image

• Les modèles d’image sont facturés à l’image selon resolution et aspectRatio (image_pricing.rates). Pour les modèles gpt-image-* et nano-banana-*, les prix affichés correspondent à un prompt court sans image de référence.
• Pour ces modèles, les images de référence et les prompts plus longs augmentent le montant facturé. Avant de créer une tâche, appelez POST /v1/generation-quotes avec le même corps : price_usd est le montant facturé pour cette requête aux prix actuels. Une tâche échouée est entièrement remboursée.

Polling et téléchargement

Seuls succeeded et failed sont des états finaux. submission_unknown signifie que l’acceptation est en cours de confirmation et result_pending en cours de finalisation : conservez l’ID de tâche d’origine, continuez l’interrogation et ne rejouez jamais la création. Après réussite, utilisez le chemin authentifié /content plutôt qu’une adresse extérieure à Open AIav. Les résultats sont conservés 24 heures (la réponse de détail contient output_expires_at ; les téléchargements expirés renvoient 410 OUTPUT_EXPIRED, enregistrez-les donc rapidement).

Migration des endpoints supprimés

Référence des codes d’erreur

Référence complète : statut HTTP, code, signification, action conseillée et classe d’erreur du SDK. Ce tableau partage sa source de données avec la correspondance des erreurs du SDK ; les nouveaux codes inconnus sont traités par le SDK selon leur statut HTTP.

Codes d’échec des tâches d’image

Lorsqu’une tâche d’image se termine avec status=failed, lisez error_code et comparez-le au tableau ci-dessous. Une tâche échouée est entièrement remboursée. Les SDK lèvent GenerationFailedError avec le même code.

Codes renvoyés uniquement dans la console