Início rápido da API do Veo 3 e do Sora — texto para vídeo e imagem para vídeo em cinco minutos

O Veo 3 e o Sora colocam o text-to-video no mesmo patamar de qualidade em que o text-to-image estava há dezoito meses. O problema: os provedores restringem o acesso com listas de espera, limitações regionais e fluxos de cobrança específicos que não se integram bem ao restante da sua stack de IA.

Na Kunavo, o modelo text-to-video disponível atualmente é o Google Veo 3, servido por um único endpoint compatível com OpenAI — sem lista de espera, autenticação compatível com OpenAI e cobrança por vídeo, com resultados servidos por uma URL permanente. O Sora (sora-2) está no roadmap: como o endpoint é independente do modelo, mudar para ele depois exigirá alterar apenas uma palavra, model. Este guia coloca sua primeira chamada do Veo 3 em funcionamento em cerca de cinco minutos. Consulte o guia da API do Sora para ver o quadro completo.

Configuração

1. Cadastre-se em kunavo.com/app/signup. Adicione saldo a partir de $10, pagando conforme o uso — o suficiente para executar várias vezes cada exemplo deste guia; seu saldo nunca expira.
2. Crie uma chave em /app/keys. Ela começa com sk-kn-.
3. Exporte-a: export KUNAVO_API_KEY=sk-kn-....

Text-to-video com o Veo 3

Atualmente, o Veo 3 é o melhor modelo text-to-video do mercado para cenas cinematográficas — entende a linguagem de câmera (dolly, push-in, rack focus), mantém a iluminação estável entre cortes e lida corretamente com movimento a 24 fps. As gerações levam de 30 segundos a alguns minutos; a resposta HTTP é síncrona — defina um timeout longo no cliente.

import requests, os, time

KEY = os.environ["KUNAVO_API_KEY"]

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "A drone shot pulling back from a quiet mountain lake at dawn, mist rising off the water. Cinematic, 24fps, soft golden light.",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
    timeout=600,   # generations take 30s to several minutes
)
resp.raise_for_status()
data = resp.json()
print(data["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.

A resposta segue o estilo da OpenAI: { data: [{ url: '...' }] }. A URL é permanente e servida por files.kunavo.com — baixe-a uma vez para seu próprio armazenamento se precisar de hospedagem de longo prazo.

Imagem para vídeo

Usar uma imagem como referência normalmente é o caminho para obter resultados com qualidade de produção. O Veo 3 oferece dois modos de imagem:

• image_mode: "frame" — uma única imagem é o primeiro quadro; duas imagens são o primeiro + o último quadro. Padrão para image_url.
• image_mode: "reference" — até 3 referências de estilo para manter a consistência de personagem / figurino sem forçar quadros.

# image-to-video: pass an image_url to anchor the first frame.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "She smiles, then walks out of frame to the left",
        "image_url": "https://files.kunavo.com/<your-upload>.jpg",
        "image_mode": "frame",      # one image => first frame
        "aspect_ratio": "9:16",     # vertical, mobile-native
    },
    timeout=600,
)
print(resp.json()["data"][0]["url"])

Se você ainda não tiver uma URL pública para a imagem de referência, envie os bytes para /v1/files e a Kunavo hospedará o arquivo para você em files.kunavo.com:

# If you don't have a public URL, upload bytes; Kunavo hosts the file.
with open("anchor.jpg", "rb") as f:
    up = requests.post(
        "https://api.kunavo.com/v1/files",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": f},
    )
image_url = up.json()["url"]   # permanent files.kunavo.com URL

Sora e outros modelos

O mesmo formato de endpoint funciona para todos os modelos de vídeo do catálogo — passe o slug correspondente ao modelo:

• veo-3 — cinematográfico, 1080p, compatível com image-to-video. Disponível agora.
• seedance-2, seedance-2-5 — da ByteDance, muito forte em movimento de personagens.

O Sora da OpenAI (sora-2) está no roadmap — ainda não pode ser chamado na Kunavo. Como /v1/video/generations é independente do modelo, no dia em que ele chegar a única alteração nas chamadas acima será o campo model; até lá, o Veo 3 é o equivalente disponível no mesmo endpoint.

Consulte /models para ver a lista atual e o preço de cada modelo.

Com Node / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

// /v1/video/generations isn't in OpenAI's SDK shape, but the same auth
// header works — call it with fetch:
const resp = await fetch(
  "https://api.kunavo.com/v1/video/generations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.KUNAVO_API_KEY}`,
    },
    body: JSON.stringify({
      model: "veo-3",
      prompt: "A red origami crane unfolding into a paper plane and flying away through a window",
      resolution: "1080p",
    }),
  },
);
const { data } = await resp.json();
console.log(data[0].url);

Modelo de preços

Os modelos de vídeo são cobrados por vídeo ou por segundo de saída, não por token: os modelos Veo por vídeo, e todo clipe tem 8 segundos; os modelos Seedance e o Wan 2.7, por segundo. A Kunavo publica a tarifa de cada modelo em /pricing. Um clipe de 8 segundos do Veo 3 em 1080p custa $0.42. Gerações que falham (4xx / 5xx) nunca são cobradas.

Checklist de produção

• Defina um timeout HTTP de 10 minutos. O gateway consulta o upstream por até 540s e retorna 504 se o modelo ainda estiver trabalhando depois disso. Para trabalhos muito longos, tente novamente — as gerações são idempotentes por prompt.
• Persista a URL do resultado. Embora as URLs de files.kunavo.com sejam permanentes, seu produto deve manter sua própria cópia no armazenamento que você controla.
• Trate respostas 429 com backoff. Os modelos de vídeo dependem de GPUs; uma breve disputa por capacidade é normal. O cabeçalho retry-after é respeitado quando presente.
• Armazene em cache por hash do prompt quando fizer sentido. Enviar o mesmo prompt duas vezes gera dois clipes e é cobrado duas vezes: o gateway não reutiliza um resultado anterior e não envia seed ao modelo.

Dúvidas: contact@kunavo.com. A equipe por trás do gateway lê todos os e-mails e responde em até 24 horas.