> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Veo Videos Generation API Integração > Veo Video Generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f) para solicitar o serviço correspondente. Após entrar na página, clique no botão "Acquire", conforme mostrado na imagem: ![](https://cdn.xhuoapi.ai/q6ytrc.png) 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 1. **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). 2. **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. 3. **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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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: ```json theme={null} { "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 é: ```json theme={null} "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: ```json theme={null} { "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: ```json theme={null} { "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/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, como mostrado na imagem: ![](https://cdn.xhuoapi.ai/tbcnai.png) 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: ```json theme={null} { "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: ![](https://cdn.xhuoapi.ai/238i32.png) O conteúdo é o seguinte: ```json theme={null} { "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 ```json theme={null} { "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.