Documentação preview

Integre a API do modelo Veo 4 ao fluxo do seu produto

Este guia mostra o fluxo planejado da Veo 4 API: criar tarefa de vídeo, consultar status, receber webhooks e planejar créditos antes do lançamento público.

Abrir API Keys Ver preços

Fluxo de integração

Conecte a API em quatro passos

Use este fluxo para preparar a integração backend. Mantenha a chave no servidor, envie jobs de forma assíncrona e salve URLs após a conclusão.

Criar uma API key

Abra Dashboard > API Keys e prepare uma chave server-side. Clientes de navegador devem chamar seu backend, sem expor a chave.

Enviar tarefa de vídeo

Envie uma requisição text-to-video ou image-to-video com prompt, mode, aspect ratio, quality e webhook URL opcional.

Acompanhar progresso

Faça polling do task endpoint com task_id até succeeded ou failed. Webhooks reduzem polling em produção.

Salvar o asset

Quando a tarefa tiver sucesso, salve video_url e thumbnail_url no CMS, editor, pipeline ou registro do usuário.

Contrato preview

Interface REST planejada

Os exemplos são concretos para que equipes possam desenhar clientes agora. Até o lançamento, trate como contrato preliminar.

Base URL

Use HTTPS a partir do servidor. O lançamento pode trazer domínio versionado ou endpoints regionais.

https://veo4api.net/api/video/veo4

Autenticação

Toda requisição usa Bearer token. Guarde API keys em server secrets, nunca em bundles frontend públicos.

Authorization: Bearer YOUR_API_KEY

POSThttps://veo4api.net/api/video/veo4/generatePode mudar

Cria uma nova tarefa assíncrona de vídeo Veo 4. A resposta retorna task_id imediatamente enquanto o render continua em background.

Campo	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	Instrução em linguagem natural para o clipe, incluindo assunto, câmera, estilo e restrições.
`image_urls`	string[]	Não	Imagens de origem públicas para jobs image-to-video. O proxy atual aceita image_urls e aliases compatíveis de URL de imagem.
`aspect_ratio`	string	Não	Valores planejados incluem 16:9, 9:16 e 1:1.
`extend_task_id`	string	Não	task_id opcional de um vídeo concluído existente ao solicitar um workflow de extensão.
`seeds`	number	Não	Seed numérico opcional para saídas mais repetíveis. O intervalo atual é de 10000 a 99999.
`watermark`	string	Não	Rótulo watermark opcional encaminhado ao backend de geração de vídeo.
`enableTranslation`	boolean	Não	Booleano opcional que controla tradução de prompt antes da geração. O padrão é true.
`public`	boolean	Não	Booleano opcional que indica se o resultado pode aparecer em áreas públicas de showcase.

cURL

curl -X POST "https://veo4api.net/api/video/veo4/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic dolly shot of a glass greenhouse during sunrise",
    "aspect_ratio": "16:9",
    "watermark": "veo4api",
    "enableTranslation": true
  }'

JavaScript

const response = await fetch("https://veo4api.net/api/video/veo4/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Animate this product photo into a smooth studio orbit shot",
    image_urls: ["https://cdn.example.com/input/product.png"],
    aspect_ratio: "1:1",
    seeds: 12345,
    public: false
  })
});

const data = await response.json();
console.log(data.task_id);

Resposta queued

{
  "task_id": "veo4_task_01j9example",
  "status": "queued",
  "model": "veo-4",
  "credits_estimated": 180,
  "created_at": "2026-05-17T08:00:00Z"
}

Resposta de tarefa concluída

{
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "progress": 100,
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "thumbnail_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.jpg",
  "completed_at": "2026-05-17T08:03:42Z"
}

// Poll the task with:
// GET https://veo4api.net/api/video/veo4/status?task_id={task_id}

Entrega assíncrona

Receba eventos de conclusão com webhooks

Entrega por webhook está planejada para o contrato público da API. Até ser ativada, consulte o status endpoint e prepare seu backend para um futuro campo webhook_url.

Política de assinatura

Os detalhes de assinatura de webhook ainda não são finais. Planeje validar um futuro signature header, guardar task_id e ignorar duplicatas.

Exemplo de webhook payload

{
  "event": "video.succeeded",
  "task_id": "veo4_task_01j9example",
  "status": "succeeded",
  "model": "veo-4",
  "video_url": "https://cdn.veo4api.net/results/veo4_task_01j9example.mp4",
  "credits_charged": 180,
  "created_at": "2026-05-17T08:00:00Z",
  "completed_at": "2026-05-17T08:03:42Z"
}

Confiabilidade

Estados de tarefa e tratamento de erros

Construa clientes com estados explícitos e falhas retryable. A geração é assíncrona, então 200 significa apenas que a tarefa foi aceita.

Estado	Significado
`queued`	A requisição foi aceita e aguarda capacidade.
`processing`	O modelo está renderizando ou pós-processando o vídeo.
`succeeded`	O vídeo está pronto e as URLs de resultado estão disponíveis.
`failed`	A geração falhou. Mostre o erro e permita revisar o prompt ou tentar novamente.
`canceled`	A tarefa foi cancelada antes da conclusão.

Código	Tratamento recomendado
`400`	Valide prompt length, image_urls, aspect_ratio, seeds e public visibility antes de tentar novamente.
`401`	API key ausente, expirada ou inválida. Peça ao usuário para criar uma nova chave.
`402`	Créditos insuficientes. Envie para billing ou reduza quality antes de tentar.
`409`	Conflito na solicitação de tarefa. Quando a plataforma retornar conflito, busque a tarefa existente.
`429`	Rate limit. Use exponential backoff e evite polling agressivo.
`500`	Erro temporário de plataforma ou modelo. Tente depois e mantenha o registro da tarefa.

Planejamento de créditos

Custos em créditos planejados

Os rótulos atuais de preço usam estes números para capacidade Veo 4. Eles não são compromisso final de cobrança antes do lançamento.

Job de vídeo standard

180

Créditos estimados por geração de vídeo Veo 4 standard.

Job de vídeo HD

240

Créditos estimados por geração de vídeo Veo 4 HD.

Use apenas para planejamento de capacidade. Limites reais da API, tiers de qualidade e cobrança podem mudar.