Veo Videos Generation API Integração

Este documento irá apresentar uma descrição da integração da API Veo Videos Generation, que pode gerar vídeos oficiais da Veo através da entrada de parâmetros personalizados.

Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da API Veo Videos Generation para solicitar o serviço correspondente. Após entrar na página, clique no botão “Acquire”, conforme mostrado na imagem:

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

Uso Básico

Primeiro, entenda a forma básica de uso, que envolve a entrada de uma palavra-chave prompt, a ação de geração action, um array de imagens de referência para o primeiro e último quadro image_urls e o modelo model, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor é text2video. Ele contém três ações principais: gerar vídeo a partir de texto (text2video), gerar vídeo a partir de imagem (image2video), e obter vídeo em 1080p (get1080p). Em seguida, precisamos inserir o modelo model, que atualmente inclui os modelos veo2, veo2-fast, veo3, veo31, veo31-fast, veo31-fast-ingredients e veo3-fast, com os detalhes a seguir:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Requisição, incluindo:

model: o modelo para gerar o vídeo, que inclui veo2, veo2-fast, veo3, veo31, veo31-fast, veo31-fast-ingredients e veo3-fast.
action: a ação da tarefa de geração de vídeo, que inclui três ações: gerar vídeo a partir de texto (text2video), gerar vídeo a partir de imagem (image2video), e obter vídeo em 1080p (get1080p).
image_urls: quando a ação de gerar vídeo a partir de imagem (image2video) é escolhida, é necessário enviar os links das imagens de referência para o primeiro e último quadro, com um máximo de três imagens de referência.
resolution: escolha a resolução do vídeo gerado, onde o modelo veo31 suporta resolução 4k, enquanto outros modelos não suportam. Todos os modelos suportam 1080p e resolução gif. Se esse valor não for passado, a resolução padrão será 720p, com as opções: 1080p, gif, 4k.
prompt: a palavra-chave.
callback_url: a URL para onde os resultados devem ser retornados.

📌 Resumo da Descrição do Modelo

Nome do Modelo	Modos Suportados	Regras de Entrada de Imagem
veo2-fast	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	Apenas suporta 1 imagem → Modo de primeiro quadro
veo3-fast	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	1 imagem → Modo de primeiro quadro 3 imagens → Modo de primeiro e último quadro
veo31-fast	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	1 imagem → Modo de primeiro quadro 3 imagens → Modo de primeiro e último quadro
veo31-fast-ingredients	❌ Gerar vídeo a partir de texto (não suportado) ✅ Fusão forçada de múltiplas imagens (imagem obrigatória)	1-3 imagens → Modo de fusão de múltiplas imagens (máximo de 3 imagens)
veo2	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	1 imagem → Modo de primeiro quadro 3 imagens → Modo de primeiro e último quadro
veo3	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	1 imagem → Modo de primeiro quadro 3 imagens → Modo de primeiro e último quadro
veo31	Gerar vídeo a partir de texto (sem imagem) Gerar vídeo a partir de imagem (com imagem)	1 imagem → Modo de primeiro quadro 3 imagens → Modo de primeiro e último quadro

🔑 Descrição das Regras Chave

Lógica Geral:
- Sem entrada de imagem → Aciona automaticamente o modo de gerar vídeo a partir de texto.
- Com entrada de imagem → Aciona o modo de gerar vídeo a partir de imagem (a ação específica é determinada pela quantidade de imagens).
Tipos de Modo de Gerar Vídeo a partir de Imagem:
- Modo de Primeiro Quadro (1 imagem): o primeiro quadro é fixado na imagem de entrada.
- Modo de Primeiro e Último Quadro (2 imagens): o primeiro e o último quadro são fixados nas imagens de entrada.
- Modo de Fusão de Múltiplas Imagens (1-3 imagens): apenas veo31-fast-ingredients suporta, fundindo o conteúdo de várias imagens para gerar o vídeo.
Classificação de Modos:
- Modo Rápido: veo2-fast, veo3-fast, veo31-fast, veo31-fast-ingredients.
- Modo de Qualidade: veo2, veo3, veo31 (geração de qualidade superior).

⚠️ Considerações Importantes

Modelo que obrigatoriamente requer imagem: veo31-fast-ingredients deve receber imagens (1-3 imagens), caso contrário, não funcionará.
Limite de quantidade de imagens:
- Exceto veo31-fast-ingredients, outros modelos suportam no máximo 3 imagens de entrada.

Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado:

{
  "success": true,
  "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
  "trace_id": "9906dac0-1516-41dc-9fe3-067ca1ba8269",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "state": "succeeded"
    }
  ]
}

O resultado retornado contém vários campos, conforme descrito a seguir:

success，o estado da tarefa de geração de vídeo neste momento.
task_id，o ID da tarefa de geração de vídeo neste momento.
data，o resultado da tarefa de geração de vídeo neste momento.
- id，o ID do vídeo da tarefa de geração de vídeo neste momento.
- video_url，o link do vídeo da tarefa de geração de vídeo neste momento.
- created_at，o horário de criação da tarefa de geração de vídeo neste momento.
- complete_at，o horário de conclusão da tarefa de geração de vídeo neste momento.
- state，o estado da tarefa de geração de vídeo neste momento.

Podemos ver que obtivemos informações satisfatórias sobre o vídeo, e só precisamos acessar o link do vídeo gerado em data. Além disso, se você quiser gerar o código correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:

curl -X POST 'https://api.xhuoapi.ai/v1/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo2",
  "prompt": "Caneca de café de cerâmica branca sobre uma bancada de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, pausando brevemente na alça."
}'

Função de Geração de Vídeo a partir de Imagens

Se você quiser gerar um vídeo a partir de imagens de quadro inicial e final, pode definir o parâmetro action como image2video e inserir um array de links das imagens de quadro inicial e final image_urls. Em seguida, precisamos preencher as próximas etapas com as palavras-chave que queremos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:

model：o modelo de geração de vídeo, que pode ser veo2, veo2-fast, veo3 e veo3-fast.
image_urls：quando a ação de geração de vídeo image2video é escolhida, é necessário fazer o upload dos links das imagens de referência de quadro inicial e final.
prompt：palavras-chave.

Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

Código correspondente em Python:

import requests

url = "https://api.xhuoapi.ai/v1/veo/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "image2video",
    "model": "veo2",
    "prompt": "Deixe-o dançar",
    "image_urls": ["https://cdn.xhuoapi.ai/7p1jhy.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Ao clicar em executar, podemos ver que obtemos um resultado, como abaixo:

{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

Podemos ver que o conteúdo do resultado é consistente com o anterior, o que também realiza a função de geração de vídeo a partir de imagens.

Função de Obtenção de Vídeo em 1080p

Se você quiser obter um vídeo Veo já gerado em 1080p, pode definir o parâmetro action como get1080p e inserir o ID do vídeo que deseja obter em 1080p. O ID do vídeo pode ser obtido com base no uso básico, como mostrado na imagem abaixo:

Neste momento, podemos ver que o ID do vídeo é:

"id": "59f12222b1fa4fbe9331ff2400ad1583"

Nota: o video_id aqui é o ID do vídeo gerado. Se você não souber como gerar um vídeo, pode consultar o uso básico mencionado anteriormente.

Em seguida, precisamos preencher as próximas etapas com as palavras-chave que queremos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:

model：o modelo de geração de vídeo, que pode ser veo2, veo2-fast, veo3 e veo3-fast.
video_id：o ID do vídeo de referência, usado para obter o vídeo em 1080p.

Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

Ao clicar em executar, podemos ver que obtemos um resultado, como abaixo:

{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

Podemos ver que o conteúdo do resultado é consistente com o anterior, o que também realiza a função de obtenção de vídeo em 1080p.

Geração de Vídeo com Tamanho Específico

Se você quiser especificar a geração de um vídeo Veo com tamanho personalizado, pode definir o parâmetro aspect_ratio como o tamanho desejado. Em seguida, precisamos preencher as próximas etapas com as palavras-chave que queremos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:

model：o modelo de geração de vídeo, que pode ser veo2, veo2-fast, veo3 e veo3-fast.
aspect_ratio：o tamanho do vídeo, atualmente suportado: 16:9, 16:9, 3:4, 4:3, 1:1, o padrão é 16:9.
translation：se deve ativar a tradução automática das palavras-chave, o padrão é false. Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

Ao clicar em executar, podemos ver que obtemos um resultado, como abaixo:

{
  "success": true,
  "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687",
  "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886",
  "data": [
    {
      "id": "fc667e7d3b8f44beaa61a3c339af0e50",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4",
      "created_at": "2025-08-24 20:09:06",
      "complete_at": "2025-08-24 20:10:45",
      "state": "succeeded"
    }
  ]
}

Pode-se ver que o conteúdo do resultado é consistente com o anterior, o que também realiza a função de gerar vídeos em tamanhos especificados.

Callback Assíncrono

Como o tempo de geração da API Veo Videos Generation é relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em um consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url adicional. Após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo de informação task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado para o callback_url especificado pelo cliente no formato POST JSON, que também incluirá o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Abaixo, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Aqui, para facilitar a demonstração, usamos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem:

Copie esta URL, que pode ser usada como Webhook, o exemplo aqui é https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc. Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, enquanto preenchemos os parâmetros correspondentes, o conteúdo específico é mostrado na imagem:

Clique em executar, e você verá que receberá imediatamente um resultado, como abaixo:

{
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"
}

Após alguns instantes, podemos observar o resultado do vídeo gerado em https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc, como mostrado na imagem:

O conteúdo é o seguinte:

{
  "success": true,
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "data": [
    {
      "id": "2f43ceed37944b4d836e1a1899dad0a1",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
      "created_at": "2025-07-25 17:19:20",
      "complete_at": "2025-07-25 17:21:45",
      "state": "succeeded"
    }
  ]
}

Pode-se ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos anteriores, permitindo que a tarefa seja associada através deste campo.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:

400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API Veo Videos Generation para gerar vídeos através de palavras-chave de entrada e imagens de referência da primeira cena. Esperamos que este documento possa ajudá-lo a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Documentation Index

​Processo de Solicitação

​Uso Básico

​📌 Resumo da Descrição do Modelo

​🔑 Descrição das Regras Chave

​⚠️ Considerações Importantes

​Função de Geração de Vídeo a partir de Imagens

​Função de Obtenção de Vídeo em 1080p

​Geração de Vídeo com Tamanho Específico

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico

📌 Resumo da Descrição do Modelo

🔑 Descrição das Regras Chave

⚠️ Considerações Importantes

Função de Geração de Vídeo a partir de Imagens

Função de Obtenção de Vídeo em 1080p

Geração de Vídeo com Tamanho Específico

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão