Guia da Sora API — geração de vídeos com IA que funciona agora (Veo 3.1)

Sora é o modelo text-to-video da OpenAI, e “Sora API” é uma forma de gerar vídeos programaticamente, não um aplicativo voltado ao consumidor. Atualmente, o text-to-video no Kunavo é executado com o Google Veo 3 por meio de um único endpoint de vídeo no estilo da OpenAI — o suporte à Sora está no roadmap e, como o endpoint não depende do modelo, migrar para a Sora mais tarde exigirá alterar apenas uma palavra. Este guia mostra o fluxo de trabalho com o Veo 3 para que todos os exemplos possam ser executados agora.

O que é a Sora API?

Sora (Sora 2 e Sora 2 Pro) transforma prompts de texto ou imagens estáticas em clipes curtos de vídeo e, na Sora 2, fornece também áudio sincronizado. Na forma de API, você pode programar a geração em um pipeline: cortes de marketing, animações de produtos, b-roll e prévias de storyboard. Os modelos de vídeo atuais têm todos o mesmo formato: envie um prompt e parâmetros e receba uma URL de vídeo hospedada.

Vídeo atual no Kunavo: Veo 3

O Kunavo oferece geração de vídeos por meio de um único endpoint no estilo da OpenAI /v1/video/generations. A Sora ainda não está ativada no catálogo, e o modelo text-to-video atualmente disponível é o Google Veo 3, que cria clipes cinematográficos com áudio nativo. Os exemplos abaixo usam veo-3 — quando a Sora for adicionada, o único campo a alterar será model.

Início rápido de text-to-video

Basta um POST com sua chave do Kunavo. A geração pode levar alguns minutos; por isso, 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": "빨간 종이학이 펼쳐지는 영화적인 돌리인, 부드러운 조명",
        "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 adicionar movimento a uma imagem estática, passe image_url (uma URL https ou um arquivo enviado para /v1/files) junto com o prompt. Para movimento controlado, você pode passar o primeiro e o último quadro usando image_urls e image_mode: "frame". O exemplo completo está na documentação de vídeo.

Ciclo de vida de uma tarefa assíncrona

Em produção, não mantenha uma conexão aberta por 10 minutos. Envie a tarefa para /v1/videos, receba imediatamente um ID de tarefa e consulte 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 aborda 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, com base em 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 ver a tabela completa de níveis.

Dicas para prompts de vídeo

• Descreva o enquadramento, não apenas o sujeito. Movimento de câmera (travelling, panorâmica, aproximação), sensação da lente, iluminação e ritmo importam mais que adjetivos.
• Especifique a proporção da tela — use 16:9 para paisagem e 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 (image-to-video). Isso é útil quando você precisa manter um personagem ou produto específico consistente.

Perguntas frequentes