Início rápido com os SDKs oficiais

Os SDKs oficiais cobrem todo o fluxo (criar → consultar → baixar), com chaves de idempotência automáticas e erros tipados. O SDK para Node não tem dependências; o de Python depende só de httpx. Por enquanto eles são distribuídos como repositórios no GitHub; a publicação no npm e no PyPI será anunciada separadamente.

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

Integração em quatro passos

1. Use a variável de ambiente OPENAIAV_API_KEY do servidor para chamar https://api.openaiav.com/v1/models e ler as chaves de modelo, os preços e os reference_modes atuais.
2. Envie prompt, referenceMode e referenceImages via POST para /v1/generations. As imagens de referência são URLs HTTPS públicas e não precisam de pré-cadastro. Em caso de sucesso, a resposta é HTTP 201.
3. Guarde o id retornado e consulte o mesmo GET /v1/generations/{id} após poll_after_ms. Continue aguardando em processing, result_pending e submission_unknown; não crie outra tarefa.
4. Quando o status for succeeded, baixe com GET /v1/generations/{id}/content. Uma resposta completa é HTTP 200, e um único intervalo de bytes é 206.

Autenticação e idempotência

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

Envie Authorization: Bearer oav_... em toda requisição e mantenha a chave no servidor. A criação exige generation:create; o polling e o download exigem generation:read. Gere uma Idempotency-Key nova (um UUID) para cada intenção de criação, para que cada execução de um exemplo receba uma chave nova; reutilize-a apenas ao repetir essa mesma criação depois de um resultado de rede incerto e nunca use a mesma chave com corpos diferentes.

Cabeçalhos da requisição

Endpoints

Passo 1: ler os recursos do modelo

Não fixe no código os recursos dos modelos. Envie apenas os modos listados em reference_modes e oculte ou bloqueie combinações incompatíveis antes do envio. O exemplo mínimo mostra uma requisição de 4 segundos, 480p e sem áudio com seedance-2.5-oa.

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

Exemplo mínimo de vídeo público

O exemplo traz o fluxo completo: criar → consultar a mesma tarefa → baixar. first_frame usa uma imagem de referência e adaptive; generateAudio=false evita pedir áudio. Os códigos de sucesso são 201, 200 e 200/206; em caso de falha, veja primeiro o HTTP e depois o 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 da requisição

Modos de referência

first_frame

first_frame: a imagem de referência vira o quadro inicial e define a composição. Envie exatamente um item em referenceImages; aspectRatio vem de aspect_ratios do modelo e fica fixo em adaptive quando o catálogo oferece essa opção (o resultado acompanha a imagem de referência). first_last_frame: envie exatamente 2 referenceImages. A ordem do array é quadro inicial e depois quadro final, e o modelo gera o que fica entre eles. As duas imagens não precisam ter as mesmas dimensões. Os modos de quadro não podem ser combinados com 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: a mídia de referência mantém a consistência do assunto, do estilo e do cenário sem virar o quadro inicial. Além de referenceImages, modelos compatíveis também aceitam referenceVideos e referenceAudios; os limites por tipo estão na tabela abaixo, e qualquer tipo que o catálogo não declare retorna 400 no envio. Os prompts citam os itens pela ordem 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"
}

Compatibilidade atual

Uma única integração para todos os modelos de vídeo: mesmo endpoint, mesmos campos. Trocar de modelo significa mudar só o model. Todas as diferenças são declaradas pelo catálogo, e a tabela abaixo é esse catálogo: para cada modelo, quais modos de referência ele aceita e quanto de cada tipo de mídia. Tudo o que o catálogo não declarar é recusado explicitamente no envio, nunca ignorado em silêncio.

Detalhes do quadro inicial e encadeamento pelo quadro final

Detalhes do quadro inicial: first_frame e omni_reference são mutuamente exclusivos, então cada requisição escolhe só um. Com a referência Omni, você pode direcionar uma imagem de referência para a abertura pelo prompt, mas, quando o quadro inicial precisar ser fiel, envie essa imagem no modo first_frame. No Seedance 2.5, tarefas com quadro inicial fixam a proporção em adaptive (o resultado acompanha o quadro inicial). Encadear pelo quadro final: passe returnLastFrame: true na criação e, se a tarefa for concluída, ela também retorna last_frame_url (um PNG sem marca d’água no tamanho do vídeo, guardado por 24 horas). Use essa URL diretamente como referenceImages do first_frame da próxima requisição para encadear várias cenas, sem nenhum pré-cadastro.

Preço de vídeos de referência

• Vídeos de referência com duração mensurável são cobrados a preço fixo, que você pode ver antes em uma prévia. Se a duração não puder ser medida, a prévia é recusada sem cobrança.
• Chame POST /v1/generation-quotes para ver o preço atual. Vídeos por URL são medidos e precificados novamente na criação; o reserved_usd da resposta é o valor real. quoteId não fixa o preço, e expires_at apenas sugere quando atualizar.
• O catálogo define duração por vídeo e total, quantidade e mínimo faturável. Cada vídeo de referência deve ter entre 2 e 15 segundos na série Seedance 2.0 e entre 2 e 30 segundos nos demais modelos compatíveis. Uma duração medida fora dos limites retorna 422 REFERENCE_DURATION_OUT_OF_RANGE sem cobrança.
• Use um link direto HTTPS público para MP4/MOV. Arquivos com tamanho conhecido acima de 200 MiB retornam REFERENCE_VIDEO_TOO_LARGE; se o tamanho não for informado, o orçamento ainda pode ser gerado. URLs privadas retornam REFERENCE_URL_NOT_PUBLIC e sondas ocupadas 429 REFERENCE_PROBE_BUSY. O limite de upload no console é 32 MiB.
• Cada tarefa é cobrada pelo preço do seu orçamento, reserved_usd, na criação; no sucesso, essa é a cobrança final, e na falha ela é totalmente reembolsada. O price_usd de uma prévia equivale ao que a criação cobraria naquele momento; informe a duração de saída, não -1.
• URLs públicas de vídeo são verificadas na prévia e novamente na criação, depois enviadas diretamente sem armazenamento ou registro. Mantenha o conteúdo estável. Uploads usam outra rota; restrições para rostos reais continuam valendo.

Preços dos modelos de imagem

• Os modelos de imagem são cobrados por imagem conforme resolution e aspectRatio (image_pricing.rates). Nos modelos gpt-image-* e nano-banana-*, os preços listados valem para um prompt curto sem imagens de referência.
• Nesses modelos, imagens de referência e prompts mais longos aumentam a cobrança. Antes de criar uma tarefa, chame POST /v1/generation-quotes com o mesmo corpo: price_usd é a cobrança dessa requisição pelos preços atuais. Tarefas com falha são totalmente reembolsadas.

Polling e download

Somente succeeded e failed são estados finais. submission_unknown indica que a aceitação está sendo confirmada e result_pending em finalização: guarde o ID da tarefa original, continue consultando e nunca repita a criação. Após a conclusão, use o caminho autenticado /content em vez de depender de endereços fora do Open AIav. Os resultados ficam guardados por 24 horas (a resposta de detalhe traz output_expires_at; downloads expirados retornam 410 OUTPUT_EXPIRED, então salve a tempo).

Migração de endpoints desativados

Referência de códigos de erro

Referência completa: status HTTP, código, significado, ação recomendada e classe de erro do SDK. Esta tabela usa a mesma fonte de dados do mapeamento de erros do SDK; códigos novos desconhecidos são tratados pelo SDK conforme o status HTTP.

Códigos de falha de tarefas de imagem

Quando uma tarefa de imagem termina com status=failed, leia error_code e confira na tabela abaixo. Tarefas com falha são totalmente reembolsadas. Os SDKs lançam GenerationFailedError com o mesmo código.

Códigos retornados apenas no console