Inicio rápido con los SDK oficiales

Los SDK oficiales encapsulan todo el flujo (crear → consultar → descargar) con claves de idempotencia automáticas y errores tipados. El SDK de Node no tiene dependencias; el de Python solo depende de httpx. De momento se distribuyen como repositorios de GitHub; su publicación en npm y PyPI se anunciará por separado.

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

Integración en cuatro pasos

1. Usa la variable de entorno OPENAIAV_API_KEY del servidor para llamar a https://api.openaiav.com/v1/models y leer las claves de modelo, los precios y los reference_modes actuales.
2. Envía prompt, referenceMode y referenceImages con POST a /v1/generations. Las imágenes de referencia son URL HTTPS públicas y no requieren registro previo. Si todo va bien, se devuelve HTTP 201.
3. Guarda el id devuelto y consulta el mismo GET /v1/generations/{id} tras poll_after_ms. Sigue esperando en processing, result_pending y submission_unknown; no crees otra tarea.
4. Cuando el estado sea succeeded, descarga con GET /v1/generations/{id}/content. Una respuesta completa es HTTP 200 y un único rango de bytes, 206.

Autenticación e idempotencia

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

Envía Authorization: Bearer oav_... en cada solicitud y guarda la clave en el servidor. La creación requiere generation:create; el sondeo y la descarga requieren generation:read. Genera una Idempotency-Key nueva (un UUID) para cada intención de creación, de modo que cada ejecución de un ejemplo obtenga una clave nueva; reutilízala solo al reintentar esa misma creación si el resultado de red es incierto y nunca uses una misma clave con cuerpos distintos.

Encabezados de la solicitud

Endpoints

Paso 1: consultar las funciones del modelo

No fijes en el código las funciones de los modelos. Envía solo los modos que aparezcan en reference_modes y oculta o bloquea las combinaciones incompatibles antes de enviar. El ejemplo mínimo muestra una solicitud de 4 segundos, 480p y sin audio con seedance-2.5-oa.

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

Ejemplo mínimo de vídeo público

El ejemplo incluye todo el flujo: crear → consultar la misma tarea → descargar. first_frame usa una imagen de referencia y adaptive; generateAudio=false evita pedir audio. Los códigos de éxito son 201, 200 y 200/206; si algo falla, revisa primero el HTTP y después 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'

Parámetros de la solicitud

Modos de referencia

first_frame

first_frame: la imagen de referencia se convierte en el primer fotograma y define la composición. Envía exactamente un elemento en referenceImages; aspectRatio sale de las aspect_ratios del modelo y queda fijado en adaptive cuando el catálogo lo ofrece (el resultado sigue a la imagen de referencia). first_last_frame: envía exactamente 2 referenceImages. El orden del array es primer fotograma y después último fotograma, y el modelo genera lo que hay entre ambos. Las dos imágenes no tienen que tener las mismas dimensiones. Los modos de fotograma no se pueden combinar con 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: los medios de referencia mantienen la coherencia del sujeto, el estilo y la escena sin convertirse en el primer fotograma. Además de referenceImages, los modelos compatibles aceptan referenceVideos y referenceAudios; los límites por tipo están en la tabla de abajo y cualquier tipo que el catálogo no declare devuelve un 400 al enviarse. Los prompts aluden a los elementos por su orden dentro de cada tipo: @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"
}

Compatibilidad actual

Una sola integración para todos los modelos de vídeo: el mismo endpoint y los mismos campos. Cambiar de modelo solo implica cambiar model. El catálogo declara todas las diferencias, y la tabla de abajo es ese catálogo: para cada modelo, qué modos de referencia admite y cuántos medios de cada tipo acepta. Todo lo que el catálogo no declare se rechaza de forma explícita al enviarlo; nunca se ignora sin avisar.

Detalles del primer fotograma y encadenado con el último

Detalles del primer fotograma: first_frame y omni_reference son excluyentes, así que cada solicitud elige uno solo. Con la referencia omni puedes orientar una imagen de referencia hacia el plano inicial mediante el prompt, pero si el primer fotograma debe coincidir exactamente, envía esa imagen en modo first_frame. En Seedance 2.5, las tareas con primer fotograma fijan la relación de aspecto en adaptive (el resultado sigue al primer fotograma). Encadenar con el último fotograma: pasa returnLastFrame: true al crear la tarea y, si se completa, también devuelve last_frame_url (un PNG sin marca de agua del tamaño del vídeo, que se conserva 24 horas). Usa esa URL directamente como referenceImages del first_frame de la siguiente solicitud para encadenar varios planos, sin ningún registro previo.

Precios de vídeos de referencia

• Los vídeos de referencia con duración medible se facturan a precio fijo, que puedes consultar antes en una vista previa. Si no se puede medir la duración, no se ofrece la vista previa ni se cobra nada.
• Llama a POST /v1/generation-quotes para ver el precio actual. Los vídeos URL se vuelven a medir y valorar al crear; reserved_usd en la respuesta de creación es el importe real. quoteId no fija el precio y expires_at solo indica cuándo actualizar.
• El catálogo fija la duración por vídeo y total, la cantidad y el mínimo facturable. Cada vídeo de referencia debe durar entre 2 y 15 segundos en la serie Seedance 2.0 y entre 2 y 30 segundos en los demás modelos compatibles. Una duración medida fuera de los límites devuelve 422 REFERENCE_DURATION_OUT_OF_RANGE sin cargo.
• Usa un enlace directo HTTPS público a MP4/MOV. Los archivos de tamaño conocido mayores de 200 MiB devuelven REFERENCE_VIDEO_TOO_LARGE; se puede cotizar sin tamaño declarado. Las URL privadas devuelven REFERENCE_URL_NOT_PUBLIC y las mediciones ocupadas 429 REFERENCE_PROBE_BUSY. Las subidas de consola se limitan a 32 MiB.
• A cada tarea se le cobra el precio de su presupuesto, reserved_usd, al crearla; si termina bien, ese es el cargo final, y si falla se reembolsa por completo. El price_usd de una vista previa equivale a lo que costaría crear la tarea en ese momento; indica la duración de salida, no -1.
• Las URL públicas de vídeo se comprueban al previsualizar y de nuevo al crear, y luego se pasan directamente al servicio de generación sin almacenamiento ni registro. Mantén estable el contenido. Las subidas siguen otra ruta y siguen vigentes las restricciones sobre rostros reales.

Precios de los modelos de imagen

• Los modelos de imagen se cobran por imagen según resolution y aspectRatio (image_pricing.rates). En los modelos gpt-image-* y nano-banana-*, los precios indicados corresponden a un prompt corto sin imágenes de referencia.
• En estos modelos, las imágenes de referencia y los prompts más largos aumentan el cobro. Antes de crear una tarea, llama a POST /v1/generation-quotes con el mismo cuerpo: price_usd es el cobro de esa solicitud a los precios actuales. Las tareas fallidas se reembolsan por completo.

Sondeo y descarga

Solo succeeded y failed son estados finales. submission_unknown indica que la aceptación se está confirmando y result_pending se está finalizando: guarda el ID de la tarea original, sigue consultando y nunca repitas la creación. Tras completarse, usa la ruta autenticada /content en lugar de depender de direcciones ajenas a Open AIav. Los resultados se conservan 24 horas (la respuesta de detalle incluye output_expires_at; las descargas caducadas devuelven 410 OUTPUT_EXPIRED, así que guárdalos a tiempo).

Migración de endpoints retirados

Referencia de códigos de error

Referencia completa: estado HTTP, código, significado, acción recomendada y clase de error del SDK. Esta tabla comparte la fuente de datos con la correspondencia de errores del SDK; los códigos nuevos que no conozca el SDK se tratan según su estado HTTP.

Códigos de fallo de tareas de imagen

Cuando una tarea de imagen termina con status=failed, lee error_code y búscalo en la tabla. Las tareas fallidas se reembolsan por completo. Los SDK lanzan GenerationFailedError con el mismo código.

Códigos que solo devuelve la consola