Referência de API

Documentação completa de API para geração de vídeo Veo 3.1 AI

Visão geral

A API Veo 3.1 permite que você gere vídeos AI programaticamente a partir de descrições de texto ou imagens. Nossa API RESTful é projetada para ser simples, poderosa e fácil de integrar em suas aplicações.

URL base

https://veo3o1.com/api

Autenticação

Todas as requisições de API requerem autenticação usando uma chave API. Inclua sua chave API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Você pode gerar chaves API no seu painel de conta.


Gerar vídeo

Crie um novo vídeo AI a partir de texto ou imagem.

Endpoint

POST /generate-video

Corpo da requisição

{
  "generationType": "text_to_video" | "image_to_video",
  "prompt": "Your video description",
  "aspectRatio": "auto" | "16:9" | "9:16",
  "imageUrl": "https://...", // Required if generationType is "image_to_video"
  "imageKey": "r2-key" // Optional, for uploaded images
}

Parâmetros

ParâmetroTipoObrigatórioDescrição
generationTypestringSimTipo de geração: text_to_video ou image_to_video
promptstringSimDescrição do vídeo que você deseja gerar
aspectRatiostringNãoProporção do vídeo. Padrão: auto
imageUrlstringCondicionalObrigatório se generationType for image_to_video
imageKeystringNãoChave de armazenamento para imagens enviadas

Resposta

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "video-uuid-123",
    "status": "pending",
    "generationType": "text_to_video",
    "prompt": "Your video description",
    "aspectRatio": "16:9",
    "createdAt": "2025-10-16T10:00:00Z"
  }
}

Exemplo

curl -X POST https://veo3o1.com/api/generate-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generationType": "text_to_video",
    "prompt": "A beautiful sunset over the ocean with waves gently lapping the shore",
    "aspectRatio": "16:9"
  }'

Obter status do vídeo

Verifique o status de uma solicitação de geração de vídeo.

Endpoint

GET /video-status/{uuid}

Parâmetros

ParâmetroTipoObrigatórioDescrição
uuidstringSimUUID do vídeo da solicitação de geração

Resposta

{
  "code": 0,
  "msg": "Success",
  "data": {
    "uuid": "video-uuid-123",
    "status": "completed" | "pending" | "processing" | "failed",
    "videoUrl": "https://...", // Available when status is "completed"
    "progress": 85, // Processing progress (0-100)
    "estimatedTime": 120 // Estimated seconds remaining
  }
}

Valores de status

  • pending: O vídeo está na fila para processamento
  • processing: O vídeo está sendo gerado
  • completed: O vídeo está pronto e disponível para download
  • failed: A geração falhou (verifique a mensagem de erro)

Enviar imagem

Envie uma imagem para geração de imagem para vídeo.

Endpoint

POST /upload-video-image

Requisição

Use multipart/form-data para enviar o arquivo de imagem.

curl -X POST https://veo3o1.com/api/upload-video-image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

Resposta

{
  "code": 0,
  "msg": "Upload successful",
  "data": {
    "imageUrl": "https://...",
    "imageKey": "r2-key-123"
  }
}

Formatos suportados

  • JPEG/JPG
  • PNG
  • WebP
  • Tamanho máximo do arquivo: 50MB

Códigos de erro

CódigoDescrição
0Sucesso
1000Parâmetros inválidos
1001Créditos insuficientes
1002Autenticação falhou
1003Limite de taxa excedido
5000Erro do servidor

Exemplo de resposta de erro

{
  "code": 1001,
  "msg": "Insufficient credits",
  "data": {
    "required": 2,
    "current": 0
  }
}

Melhores práticas

  1. Polling responsável: Verifique o status do vídeo a cada 5-10 segundos, não continuamente
  2. Tratamento de erros: Implemente lógica de retry com backoff exponencial
  3. Cache de resultados: Armazene vídeos gerados para evitar regeneração
  4. Use webhooks: Mais eficiente que polling para notificações de conclusão
  5. Valide entradas: Verifique o comprimento do prompt e formatos de imagem antes das chamadas API

Suporte

Precisa de ajuda com a API?