API Sora — texto-para-vídeo em um fluxo compatível com OpenAI

O Sora é o modelo de texto-para-vídeo da OpenAI, e “a API Sora” é como as equipes geram vídeo de forma programática em vez de pelo app de consumo. Na Kunavo hoje, a geração de texto-para-vídeo roda no Google Veo 3 por um único endpoint de vídeo no estilo OpenAI — o acesso ao Sora está no roadmap, e como o endpoint é agnóstico ao modelo, migrar para o Sora depois é uma mudança de uma só palavra. Este guia mostra o fluxo de trabalho com o Veo 3 para que todo exemplo funcione agora.

O que é a API Sora?

O Sora (Sora 2 e Sora 2 Pro) transforma um prompt de texto — ou uma imagem estática — em um clipe curto de vídeo, com áudio sincronizado no Sora 2. A forma de API permite roteirizar a geração dentro de um pipeline: tomadas de marketing, animações de produto, b-roll, prévias de storyboard. O formato é o mesmo entre os modelos de vídeo modernos: você envia um prompt e parâmetros e recebe de volta a URL de um vídeo hospedado.

Vídeo na Kunavo hoje: Veo 3

A Kunavo expõe a geração de vídeo por um único endpoint no estilo OpenAI, /v1/video/generations. O Sora ainda não está habilitado no catálogo; o modelo de texto-para-vídeo ao vivo é o Google Veo 3, que produz clipes cinematográficos com áudio nativo. Os exemplos abaixo usam veo-3 — quando o Sora chegar, a única mudança será o campo model.

Quickstart de texto-para-vídeo

Um POST com sua chave Kunavo. A geração pode levar alguns minutos, então a chamada síncrona mantém a conexão aberta até o clipe ficar pronto:

import requests

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "um dolly-in cinematográfico em um origami de garça vermelha se abrindo, luz suave",
        "duration": 5,
        "aspect_ratio": "16:9",
    },
    timeout=600,  # a geração pode levar minutos
)
print(resp.json()["data"][0]["url"])

Imagem-para-vídeo

Para animar uma imagem estática, passe image_url (uma URL https ou um arquivo enviado a /v1/files) junto com o prompt. Para movimento controlado, você pode passar um primeiro e um último quadro com image_urls e image_mode: "frame". Há exemplos completos na documentação de vídeo.

Ciclo de vida da tarefa assíncrona

Em produção, não segure uma conexão de 10 minutos. Envie uma tarefa para /v1/videos, receba um id de tarefa de imediato e então faça polling em GET /v1/videos/{id} até concluir. As URLs de resultado são permanentes.

# Produção: envie uma tarefa e faça polling — sem conexão de longa duração.
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "meu-uuid-de-tarefa",   # seguro para retry em ~24h
    },
    json={"model": "veo-3", "prompt": "...", "duration": 5, "aspect_ratio": "16:9"},
    timeout=60,
).json()
# depois faça polling em GET /v1/videos/{task["id"]} até concluir

A documentação de vídeo cobre o loop completo de polling, chaves de idempotência e entrega por webhook.

Preços

O Veo 3 é cobrado por vídeo (por clipe de 8 segundos em 720p, mostrado aqui), cerca de 50–70% abaixo do preço de lista do Google. Resoluções maiores custam mais — veja a página de preços para a tabela completa de faixas.

Dicas de prompt para vídeo

• Descreva a tomada, não só o sujeito. Movimento de câmera (dolly, pan, push-in), sensação de lente, iluminação e ritmo importam mais do que adjetivos.
• Defina a proporção explicitamente — 16:9 para paisagem, 9:16 para vertical/redes sociais.
• Mantenha os clipes curtos. 5–8 segundos é o ponto ideal; costure várias gerações para sequências mais longas.
• Use um quadro de referência (imagem-para-vídeo) quando precisar que um personagem ou produto específico se mantenha consistente.

FAQ