Processo de solicitação
Para usar a API Veo Videos Generation, primeiro obtenha seu API Token no console Ace Data Cloud e guarde-o para uso posterior.
Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login; após a conclusão, você retornará automaticamente à página atual.
Um API Token pode chamar todos os serviços da plataforma, sem a necessidade de solicitar separadamente para cada serviço. A primeira solicitação oferece créditos gratuitos para experimentação gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.
📘 Documentação completa: Veo Videos Generation API →
Uso básico
Primeiro, vamos entender o método básico de uso: basta inserir o promptprompt, a ação de geração action, o array de imagens de referência de primeiro e último quadro image_urls e o modelo model para obter o resultado processado. Primeiro, é necessário passar simplesmente um campo action, cujo valor é text2video. Ele contém principalmente três comportamentos: texto para vídeo (text2video), imagem para vídeo (image2video) e obter vídeo em 1080p (get1080p). Em seguida, também precisamos inserir o modelo model; atualmente, há principalmente os modelos veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients, e os detalhes são os seguintes:
accept: qual formato de resultado de resposta deseja receber; aqui é preenchido comoapplication/json, ou seja, o formato JSON.authorization: a chave para chamar a API, que pode ser selecionada diretamente em uma lista suspensa após a solicitação.
model: o modelo para gerar vídeos, principalmente os modelosveo31-fast,veo3,veo31,veo3-fasteveo31-fast-ingredients.action: o comportamento desta tarefa de geração de vídeo, contendo principalmente três comportamentos: texto para vídeo (text2video), imagem para vídeo (image2video) e obter vídeo em 1080p (get1080p).image_urls: ao selecionar o comportamento de imagem para vídeoimage2video, são necessários links das imagens de referência a serem enviadas.veo31-fast-ingredientsaceita no máximo 3 imagens (fusão de múltiplas imagens), e os demais modelos aceitam no máximo 2 imagens (modo de primeiro e último quadro).resolution: selecione a resolução do vídeo gerado; entre eles, o modelo veo31 suporta resolução 4k, enquanto os outros modelos não. Todos os modelos suportam resoluções 1080p e gif. Se este valor não for passado, a resolução 720p será usada por padrão. As opções principais são:1080p,gif,4k.prompt: prompt.callback_url: a URL que precisa receber o resultado de callback.async: opcional; quando definido comotrue, a interface retorna imediatamente otask_id, sem a necessidade de fornecercallback_url; posteriormente, o resultado é obtido por polling através da interface correspondente de consulta de tarefas.
📌 Resumo da descrição dos modelos
🔑 Descrição das regras principais
- Lógica geral:
- Sem entrada de imagem → aciona automaticamente o modo de texto para vídeo.
- Com entrada de imagem → aciona o modo de imagem para vídeo (o comportamento específico é determinado pela quantidade de imagens).
- Tipos do modo de imagem para vídeo:
- Modo de primeiro quadro (1 imagem): o primeiro quadro é fixado como a imagem de entrada.
- Modo de primeiro e último quadro (2 imagens): o primeiro e o último quadro são fixados como as imagens de entrada.
- Modo de fusão de múltiplas imagens (1-3 imagens): suportado apenas por
veo31-fast-ingredients, combina o conteúdo de múltiplas imagens para gerar vídeos.
- Classificação dos modos:
- Modo Fast:
veo3-fast,veo31-fast,veo31-fast-ingredients. - Modo Quality:
veo3,veo31(maior qualidade de geração).
⚠️ Observações
- Único modelo com envio obrigatório de imagens:
veo31-fast-ingredientsdeve receber imagens (1-3 imagens), caso contrário não poderá ser executado. - Limite de quantidade de imagens:
veo31-fast-ingredientssuporta entrada de 1-3 imagens (modo de fusão de múltiplas imagens).- Os outros modelos suportam no máximo 2 imagens de entrada (modo de primeiro e último quadro).
success, o status atual da tarefa de geração de vídeo.task_id, o ID atual da tarefa de geração de vídeo.data, o resultado atual da tarefa de geração de vídeo.id, o ID do vídeo da tarefa de geração de vídeo atual.video_url, o link do vídeo da tarefa de geração de vídeo atual.created_at, o horário de criação da tarefa de geração de vídeo atual.complete_at, o horário de conclusão da tarefa de geração de vídeo atual.state, o status da tarefa de geração de vídeo atual.
data no resultado.
Além disso, se quiser gerar o código de integração correspondente, você pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:
Funcionalidade de imagem para vídeo
Se quiser gerar um vídeo com base em imagens do quadro inicial e final, você pode definir o parâmetroaction como image2video e inserir o array de links das imagens dos quadros inicial e final image_urls.
Em seguida, precisamos preencher os prompts que precisam ser estendidos na próxima etapa para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:
model: o modelo para gerar vídeos, principalmenteveo31-fast,veo3,veo31,veo3-fasteveo31-fast-ingredients.image_urls: ao selecionar a ação de imagem para vídeoimage2video, é obrigatório fornecer os links das imagens de referência a serem enviadas.prompt: o prompt.
Funcionalidade para obter vídeo em 1080p
Se quiser obter 1080p para um vídeo Veo já gerado, você pode definir o parâmetroaction como get1080p e inserir o ID do vídeo para o qual deseja obter 1080p. O ID do vídeo é obtido com base no uso básico, conforme mostrado na imagem abaixo:
Observação: aqui, o video_id no vídeo é o ID do vídeo após sua geração. Se você não souber como gerar vídeos, pode consultar o uso básico acima para gerar um vídeo.
Em seguida, precisamos preencher os prompts que precisam ser estendidos na próxima etapa para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:
model: o modelo para gerar vídeos, principalmenteveo31-fast,veo3,veo31,veo3-fasteveo31-fast-ingredients.video_id: o ID do vídeo de referência, usado para obter o vídeo em 1080p.
Geração com tamanho de vídeo especificado
Se quiser especificar a geração de um vídeo Veo com dimensões personalizadas, você pode definir o parâmetroaspect_ratio para o tamanho desejado. Em seguida, precisamos preencher os prompts que precisam ser estendidos na próxima etapa para personalizar a geração do vídeo, podendo especificar o seguinte conteúdo:
model: o modelo para gerar vídeos, principalmenteveo31-fast,veo3,veo31,veo3-fasteveo31-fast-ingredients.aspect_ratio: o tamanho do vídeo, atualmente compatível com:16:9,16:9,3:4,4:3,1:1, sendo o padrão16:9.translation: se deve ativar a tradução automática do prompt, o padrão éfalse. O exemplo de preenchimento é o seguinte:
Callback assíncrono
Como o tempo de geração da Veo Videos Generation API é relativamente longo, levando cerca de 1 a 2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão ativa, 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 uma solicitação, ele especifica adicionalmente um campocallback_url. Após o cliente iniciar uma solicitação de API, a API retornará imediatamente um resultado, contendo informações do campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado na forma de POST JSON para o callback_url especificado pelo cliente, que também inclui o campo task_id, permitindo assim que os resultados da tarefa sejam associados pelo ID.
A seguir, vamos entender como operar especificamente por meio de um exemplo.
Primeiro, o callback de Webhook é um serviço que pode receber solicitações HTTP, e o desenvolvedor deve substituí-lo pela URL de um servidor HTTP criado por ele mesmo. Para facilitar a demonstração, é utilizado aqui um site público de exemplo de Webhook, https://webhook.site/. Ao abrir esse site, é possível obter uma URL de Webhook, como mostrado na imagem:
Copie esta URL para usá-la como Webhook; o exemplo aqui é https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc.
Em seguida, podemos definir o campo callback_url como a URL de Webhook acima e preencher os parâmetros correspondentes; o conteúdo específico é mostrado na imagem:
https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc, como mostrado na imagem:
O conteúdo é o seguinte:
task_id no resultado, e os outros campos são semelhantes aos anteriores; por meio desse campo, é possível implementar a associação de tarefas.
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.