> ## 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.

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

> Gemini AI API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

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

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

Depois, use esse `task_id` como `id` para consultar a [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks); após a conclusão da tarefa, você poderá obter o novo vídeo gerado (este é o resultado real retornado neste exemplo):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/gemini-tasks) (`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`:

```json theme={null}
{
  "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`):

```json theme={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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.