Veo Videos Generation API Integração

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 para obter seu Token de API, que deve ser guardado para uso futuro.

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.

📘 Documentação Completa: Veo Videos Generation API →

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

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).
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.
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:

{
  "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:

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:

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:

{
  "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 é:

"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:

{
  "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:

{
  "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/, 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, conforme 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.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

{
  "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.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Veo Videos Generation API Integração

Processo de Solicitação

Uso Básico

📌 Resumo das Descrições dos Modelos

🔑 Descrição das Regras Principais

⚠️ 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 das Descrições dos Modelos

​🔑 Descrição das Regras Principais

​⚠️ 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 das Descrições dos Modelos

🔑 Descrição das Regras Principais

⚠️ 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