> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Veo Videos Generation API Integração > Veo Video Generation API guide - Ace Data Cloud Este documento irá apresentar uma integração com a Veo Videos Generation API, que pode gerar vídeos oficiais da Veo através da entrada de parâmetros personalizados. ## Processo de Solicitação Para usar a Veo Videos Generation API, primeiro acesse o [Painel de Controle da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. **Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço.** A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no [painel](https://platform.acedata.cloud/console/coin). > 📘 Documentação Completa: [Veo Videos Generation API →](https://platform.acedata.cloud/documents/veo-videos) ## Uso Básico Primeiro, entenda a forma básica de uso, que envolve a entrada de uma palavra-chave `prompt`, uma ação `action`, um array de imagens de referência `image_urls` e o modelo `model`, para obter o resultado processado. Primeiro, é necessário passar um campo `action`, cujo valor deve ser `text2video`, que inclui três tipos de ações: vídeo gerado por texto (`text2video`), vídeo gerado por imagem (`image2video`), e obter vídeo em 1080p (`get1080p`). Em seguida, precisamos inserir o modelo `model`, que atualmente inclui os modelos `veo31-fast`, `veo3`, `veo31`, `veo3-fast` e `veo31-fast-ingredients`, com os detalhes a seguir:

Aqui, podemos ver que 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 `veo31-fast`, `veo3`, `veo31`, `veo3-fast` e `veo31-fast-ingredients`. * `action`: a ação para a tarefa de geração de vídeo, que inclui três ações: vídeo gerado por texto (`text2video`), vídeo gerado por imagem (`image2video`), e obter vídeo em 1080p (`get1080p`). * `image_urls`: quando a ação de vídeo gerado por imagem `image2video` é escolhida, é necessário enviar os links das imagens de referência. O modelo `veo31-fast-ingredients` aceita até 3 imagens (fusão de múltiplas imagens), enquanto os outros modelos aceitam até 2 imagens (modo de quadro inicial e final). * `resolution`: escolha a resolução do vídeo gerado, onde o modelo veo31 suporta resolução 4k, enquanto os 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, dividindo-se em: `1080p`, `gif`, `4k`. * `prompt`: palavra-chave. * `callback_url`: URL para onde os resultados devem ser retornados. * `async`: opcional, se definido como `true`, a interface retorna imediatamente `task_id`, sem necessidade de fornecer `callback_url`, e os resultados podem ser obtidos posteriormente através da interface de consulta de tarefas correspondente. ### 📌 Resumo das Descrições dos Modelos | **Nome do Modelo** | **Modos Suportados** | **Regras de Entrada de Imagem** | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **veo3-fast** | Vídeo gerado por texto (sem imagem)
Modo de vídeo gerado por imagem (com imagem) | **1 imagem** → Modo de quadro inicial
**2 imagens** → Modo de quadro inicial e final | | **veo31-fast** | Vídeo gerado por texto (sem imagem)
Modo de vídeo gerado por imagem (com imagem) | **1 imagem** → Modo de quadro inicial
**2 imagens** → Modo de quadro inicial e final | | **veo31-fast-ingredients** | ❌ Vídeo gerado por texto (não suportado)
✅ **Fusão de múltiplas imagens obrigatória** (imagens devem ser enviadas) | **1-3 imagens** → Modo de fusão de múltiplas imagens (máximo de 3 imagens) | | **veo3** | Vídeo gerado por texto (sem imagem)
Modo de vídeo gerado por imagem (com imagem) | **1 imagem** → Modo de quadro inicial
**2 imagens** → Modo de quadro inicial e final | | **veo31** | Vídeo gerado por texto (sem imagem)
Modo de vídeo gerado por imagem (com imagem) | **1 imagem** → Modo de quadro inicial
**2 imagens** → Modo de quadro inicial e final | *** ### 🔑 Descrição das Regras Principais 1. **Lógica Geral**: * **Sem entrada de imagem** → Aciona automaticamente o modo de vídeo gerado por texto. * **Com entrada de imagem** → Aciona o modo de vídeo gerado por imagem (o comportamento específico é determinado pelo número de imagens). 2. **Tipos de Modo de Vídeo Gerado por Imagem**: * **Modo de Quadro Inicial** (1 imagem): o quadro inicial é fixo na imagem de entrada. * **Modo de Quadro Inicial e Final** (2 imagens): o quadro inicial e final são fixos 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 múltiplas imagens para gerar o vídeo. 3. **Classificação de Modos**: * **Modo Rápido**: `veo3-fast`, `veo31-fast`, `veo31-fast-ingredients`. * **Modo de Qualidade**: `veo3`, `veo31` (geração de qualidade superior). *** ### ⚠️ Considerações Importantes * **Modelo que obrigatoriamente requer imagens**: `veo31-fast-ingredients` deve receber imagens (1-3 imagens), caso contrário, não funcionará. * **Limite de número de imagens**: * `veo31-fast-ingredients` suporta **1-3 imagens** de entrada (modo de fusão de múltiplas imagens). * Outros modelos suportam no máximo **2 imagens** de entrada (modo de quadro inicial e final). Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como 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": "697ea2fc-58fd-48c8-8191-29041ff23c3c", "trace_id": "70e1cb12-c619-4292-a416-90191205996b", "data": [ { "id": "24ac06a5-9cc7-448f-802e-0b4db19f6e96", "video_url": "https://platform2.cdn.acedata.cloud/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a.mp4", "created_at": "2026-06-30T04:01:50.364Z", "complete_at": "2026-06-30T04:03:20.495Z", "state": "succeeded" } ] } ``` O resultado retornado contém vários campos, que são descritos 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.acedata.cloud/veo/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "veo31-fast", "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 de imagens `image_urls`. Em seguida, precisamos preencher as palavras-chave que precisamos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo: * `model`：o modelo de vídeo gerado, que pode ser `veo31-fast`、`veo3`、`veo31`、`veo3-fast` e `veo31-fast-ingredients`. * `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. * `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.acedata.cloud/veo/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "image2video", "model": "veo31-fast", "prompt": "Deixe-o dançar", "image_urls": ["https://cdn.acedata.cloud/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.acedata.cloud/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 palavras-chave que precisamos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo: * `model`：o modelo de vídeo gerado, que pode ser `veo31-fast`、`veo3`、`veo31`、`veo3-fast` e `veo31-fast-ingredients`. * `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.acedata.cloud/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 gerar um vídeo Veo com um tamanho personalizado, pode definir o parâmetro `aspect_ratio` como o tamanho desejado. Em seguida, precisamos preencher as palavras-chave que precisamos expandir para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo: * `model`：o modelo de vídeo gerado, que pode ser `veo31-fast`、`veo3`、`veo31`、`veo3-fast` e `veo31-fast-ingredients`. * `aspect_ratio`：o tamanho do vídeo, atualmente suportando: `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.acedata.cloud/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 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.acedata.cloud/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, conforme 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.acedata.cloud/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.acedata.cloud/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.