Como usar a Sora API — geração de vídeos com IA que funciona agora (Veo 3.1 / compatível com OpenAI)

Sora é o modelo da OpenAI para gerar vídeos a partir de texto, e “API Sora” é a forma de gerar vídeos programaticamente, não por um aplicativo para consumidores. Na Kunavo, a geração de texto para vídeo atualmente usa o Google Veo 3 por meio de um único endpoint de vídeo no estilo OpenAI — o suporte ao Sora está no roadmap e, como o endpoint é independente do modelo, migrar para Sora depois exigirá apenas trocar uma palavra. Este guia demonstra o fluxo com o Veo 3 para que todos os exemplos funcionem agora.

O que é a API Sora?

Sora (Sora 2 e Sora 2 Pro) transforma prompts de texto — ou uma única imagem estática — em clipes curtos de vídeo, com áudio sincronizado no Sora 2. Ao usar Sora por meio de uma API, você pode incorporar a geração a um pipeline para criar vídeos de marketing, animações de produtos, b-roll, prévias de storyboards e outros conteúdos. O formato é comum aos modelos de vídeo modernos: envie prompts e parâmetros e receba uma URL de vídeo hospedada.

Vídeo disponível agora na Kunavo: Veo 3

A Kunavo disponibiliza a geração de vídeo em 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 disponível atualmente é o Google Veo 3, que gera clipes cinematográficos com áudio nativo. Os exemplos abaixo usam veo-3 — quando o Sora chegar, você só precisará alterar o campo model.

Início rápido de texto para vídeo

Basta fazer um POST com sua chave Kunavo. Como a geração pode levar alguns minutos, 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": "a cinematic dolly-in on a red origami crane unfolding, soft light",
        "aspect_ratio": "16:9",
    },
    timeout=600,  # 生成には数分かかることがあります
)
print(resp.json()["data"][0]["url"])

duration (em segundos) define a duração do clipe nos modelos cobrados por segundo: os modelos Seedance e o Wan 2.7. Os modelos Veo ignoram esse valor; cada clipe do Veo tem 8 segundos e é cobrado por vídeo.

Imagem para vídeo

Para animar uma imagem estática, envie image_url junto com o prompt (uma URL https ou um arquivo enviado para /v1/files). Para controlar o movimento, envie o primeiro e o último quadro usando image_urls e image_mode: "frame". Exemplos detalhados estão na documentação de vídeo.

Ciclo de vida de tarefas assíncronas

Em produção, não mantenha uma conexão aberta por 10 minutos. Enfileire a tarefa em /v1/videos; um ID de tarefa será retornado imediatamente e você poderá consultar GET /v1/videos/{id} até a conclusão. A URL do resultado é permanente.

# 本番: タスクを投入してからポーリング——長時間の接続を保持しません。
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # 約 24 時間はリトライしても安全
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# その後 GET /v1/videos/{task["id"]} を完了までポーリングします

A documentação de vídeo explica o loop completo de consulta, as chaves de idempotência e a entrega por webhook.

Preços

O Veo 3 é cobrado por vídeo (aqui, por um clipe de 8 segundos em 720p) e custa cerca de 50〜70% menos que o preço de tabela do Google. Resoluções maiores custam mais — consulte a página de preços para a tabela completa de níveis.

Dicas para prompts de vídeo

• Descreva o plano, não apenas o objeto. Movimento de câmera (dolly, panorâmica, push-in), textura da lente, iluminação e ritmo funcionam melhor que adjetivos.
• Especifique a proporção — 16:9 para paisagem, 9:16 para retrato/redes sociais.
• Cada clipe do Veo tem 8 segundos. Planeje cada cena para essa duração e una várias gerações para sequências mais longas.
• Use quadros de referência (imagem para vídeo) — isso ajuda a manter consistentes personagens ou produtos específicos.

Perguntas frequentes