Instruções de integração da API Gemini Videos Generation

Este artigo apresentará as instruções de integração da API Gemini Videos Generation, que pode gerar vídeos do Google Gemini (omni-flash) por meio da inserção de prompts de texto (e imagens de referência opcionais).

Processo de solicitação

Para usar a API Gemini Videos Generation, primeiro acesse o Console Ace Data Cloud para obter seu API Token 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 único API Token permite chamar todos os serviços da plataforma, sem a necessidade de solicitar um para cada serviço separadamente. A primeira solicitação oferece créditos gratuitos para uma experiência sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.

📘 Documentação completa: Gemini Videos Generation API →

Uso básico

Primeiro, vamos entender o método básico de uso: basta inserir o prompt prompt, o modelo model e a proporção aspect_ratio para gerar o vídeo correspondente. Você pode ver que aqui configuramos os Request Headers, incluindo:

accept: o formato da resposta que se deseja receber; aqui, preencha com application/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.

Também configuramos o Request Body, incluindo:

prompt: o prompt de texto que descreve o conteúdo de vídeo que se deseja gerar, obrigatório.
model: o modelo para gerar vídeos; atualmente, apenas omni-flash é suportado, e o padrão é omni-flash.
aspect_ratio: a proporção do vídeo gerado; é possível escolher 16:9 (horizontal) ou 9:16 (vertical), sendo o padrão 16:9.
resolution: a resolução de saída opcional; é possível escolher 720p ou 1080p, sendo o padrão 720p.
image_urls: um array opcional de links de imagens de referência, usado para orientar a geração do vídeo; itens vazios serão ignorados. Ao usar video_urls para edição de vídeo, este parâmetro é obrigatório (pelo menos uma imagem).
video_urls: um array opcional de links de vídeos de referência (no máximo 1), usado para edição de vídeo / referência de vídeo; ao fornecê-lo, é necessário também fornecer pelo menos uma image_urls.
callback_url: endereço de callback assíncrono; após a configuração, a API retornará imediatamente o task_id e enviará o resultado por POST para esse endereço quando a tarefa for concluída.
async: opcional; quando definido como true, a interface retorna imediatamente o task_id, sem a necessidade de fornecer callback_url; em seguida, obtenha o resultado por polling por meio da interface de consulta de tarefas correspondente.

Clique no botão 「Try」 para realizar o teste, e o resultado obtido será semelhante ao seguinte:

{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

O resultado retornado possui vários campos, descritos a seguir:

success: se esta solicitação de geração de vídeo foi bem-sucedida.
task_id: o ID desta tarefa de geração de vídeo.
trace_id: o ID de rastreamento desta solicitação, usado para investigar problemas.
data: a lista de resultados de vídeos gerados.
- id: o identificador exclusivo do vídeo gerado.
- video_url: o endereço do link do vídeo gerado (null quando state for pending).
- state: o status da tarefa de geração de vídeo; as opções são pending / succeeded / failed.
- aspect_ratio: a proporção deste vídeo, consistente com o parâmetro da solicitação.
- prompt: o prompt usado para gerar este vídeo.

Em retornos síncronos, o nível superior também incluirá campos como started_at, finished_at, elapsed (tempo decorrido, em segundos) e cost (cobrança desta vez, em unidades de Credit). Basta obter o vídeo gerado de acordo com o endereço do link video_url em data no resultado. O código CURL correspondente é o seguinte:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

O código Python correspondente é o seguinte:

import requests

url = "https://api.acedata.cloud/gemini/videos"

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

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

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

Geração de vídeo a partir de imagem

Se quiser gerar um vídeo com base em imagens de referência, você pode inserir um ou mais links de imagens em image_urls para orientar a geração do vídeo:

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

Edição de vídeo / vídeo de referência (vídeo de entrada, vídeo gerado)

É possível diretamente 「inserir um vídeo e gerar um novo vídeo」: insira um link de vídeo de referência em video_urls (no máximo 1), e ao mesmo tempo forneça pelo menos uma imagem de referência em image_urls (requisito obrigatório upstream), depois use prompt para descrever o efeito de edição desejado (alterar estilo, trocar cenário, adicionar ou remover elementos etc.). A seguir está um exemplo real completo — transformar um vídeo de uma praia ensolarada em uma cena de inverno com neve caindo, mantendo ao mesmo tempo o layout da praia, dos coqueiros e do pequeno barco. A edição de vídeo leva mais tempo (cerca de 6,5 minutos neste exemplo), portanto use async: true para envio assíncrono:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

Após o envio, a API retorna imediatamente o task_id:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Depois, use esse task_id como id para consultar a Gemini Tasks API; após a conclusão da tarefa, você poderá obter o novo vídeo gerado (este é o resultado real retornado neste exemplo):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Se precisar de resultados em maior resolução, você pode definir resolution como 1080p (os demais parâmetros permanecem inalterados).

Dica: os links de mídia de entrada/saída no exemplo são todos resultados reais gerados. Os links de vídeos e imagens gerados pela plataforma têm um período de retenção e expirarão após esse período; faça o download e salve-os em seu próprio armazenamento assim que obtiver os resultados.

Atenção: é permitido no máximo 1 vídeo de referência; além disso, ao fornecer video_urls, é obrigatório fornecer pelo menos uma image_urls, caso contrário, o seguinte erro de parâmetro será retornado:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

Retorno de chamada assíncrono

A geração de vídeo requer algum tempo de processamento. Se não desejar manter uma conexão longa em espera, você pode fornecer callback_url; nesse caso, a API retornará imediatamente o task_id e, após a conclusão da tarefa, enviará o resultado final por POST para esse endereço:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

O resultado retornado imediatamente é o seguinte:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

Consultar o resultado da tarefa

Se você utilizou o retorno de chamada assíncrono ou deseja consultar ativamente o status da tarefa, pode usar a Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks) para consultar o status e o resultado mais recentes da tarefa com base no task_id. No corpo da solicitação, passe o task_id retornado ao criar o vídeo como id:

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

O resultado retornado após a conclusão da tarefa é semelhante ao seguinte; a estrutura de response.data é igual à da geração síncrona (durante a geração, state é pending e video_url é null):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

Tratamento de erros

Quando houver problemas com a solicitação, a API retornará o código de erro e a descrição correspondentes. Os mais comuns são:

400: os parâmetros da solicitação estão incorretos, por exemplo, falta prompt ou o valor de aspect_ratio é inválido.
401: falha na autenticação; o token é inválido ou não corresponde à API.
403: saldo insuficiente ou o prompt foi rejeitado por acionar a moderação de conteúdo.
500: erro interno do servidor ou falha na geração upstream.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Instruções de integração da API Gemini Videos Generation

Processo de solicitação

Uso básico

Geração de vídeo a partir de imagem

Edição de vídeo / vídeo de referência (vídeo de entrada, vídeo gerado)

Retorno de chamada assíncrono

Consultar o resultado da tarefa

Tratamento de erros

​Processo de solicitação

​Uso básico

​Geração de vídeo a partir de imagem

​Edição de vídeo / vídeo de referência (vídeo de entrada, vídeo gerado)

​Retorno de chamada assíncrono

​Consultar o resultado da tarefa

​Tratamento de erros

Processo de solicitação

Uso básico

Geração de vídeo a partir de imagem

Edição de vídeo / vídeo de referência (vídeo de entrada, vídeo gerado)

Retorno de chamada assíncrono

Consultar o resultado da tarefa

Tratamento de erros