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

# Guía de integración de Gemini Videos Generation API

> Gemini AI API guide - Ace Data Cloud

Este artículo presentará la guía de integración de Gemini Videos Generation API, que puede generar videos de Google Gemini (omni-flash) mediante la introducción de indicaciones de texto (y opcionalmente imágenes de referencia).

## Proceso de solicitud

Para usar Gemini Videos Generation API, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo.

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

Si aún no ha iniciado sesión o se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; una vez completado, volverá automáticamente a la página actual.

**Un API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud otorgará créditos gratuitos para una experiencia gratuita; cuando los créditos sean insuficientes, puede recargar el saldo general en la [consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

## Uso básico

Primero conozcamos el modo de uso básico: introduzca la indicación `prompt`, el modelo `model` y la relación de aspecto `aspect_ratio`, y podrá generar el video correspondiente.

Aquí puede verse que configuramos los Request Headers, incluyendo:

* `accept`: qué formato de resultado de respuesta se desea recibir; aquí se completa con `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API; después de solicitarla puede seleccionarse directamente en el menú desplegable.

Además, se configuró el Request Body, incluyendo:

* `prompt`: la indicación de texto que describe el contenido de video que se desea generar, **obligatorio**.
* `model`: el modelo para generar videos; actualmente solo se admite `omni-flash`, y el valor predeterminado es `omni-flash`.
* `aspect_ratio`: la relación de aspecto del video generado; se puede elegir `16:9` (horizontal) o `9:16` (vertical), el valor predeterminado es `16:9`.
* `resolution`: la resolución de salida opcional; se puede elegir `720p` o `1080p`, el valor predeterminado es `720p`.
* `image_urls`: un arreglo opcional de enlaces de imágenes de referencia, utilizado para guiar la generación de video; los elementos vacíos se ignorarán. Al usar `video_urls` para la edición de video, este parámetro es obligatorio (al menos una imagen).
* `video_urls`: un arreglo opcional de enlaces de videos de referencia (máximo 1), utilizado para la **edición de video / referencia de video**; al proporcionarlo, se debe proporcionar simultáneamente al menos una `image_urls`.
* `callback_url`: dirección de callback asíncrono; después de configurarla, la API devolverá inmediatamente `task_id`, y cuando la tarea se complete enviará el resultado mediante POST a esa dirección.
* `async`: opcional; al establecerlo como `true`, la interfaz devolverá inmediatamente `task_id`, sin necesidad de proporcionar `callback_url`; posteriormente, obtenga el resultado mediante sondeo a través de la interfaz de consulta de tareas correspondiente.

Haga clic en el botón «Try» para realizar una prueba; el resultado obtenido será similar al siguiente:

```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
  }
}
```

El resultado devuelto contiene múltiples campos, que se presentan a continuación:

* `success`: si esta solicitud de generación de video fue exitosa.
* `task_id`: el ID de esta tarea de generación de video.
* `trace_id`: el ID de seguimiento de esta solicitud, utilizado para investigar problemas.
* `data`: la lista de resultados de video generados.
  * `id`: el identificador único del video generado.
  * `video_url`: la dirección de enlace del video generado (es `null` cuando `state` es `pending`).
  * `state`: el estado de la tarea de generación de video; se puede elegir entre `pending` / `succeeded` / `failed`.
  * `aspect_ratio`: la relación de aspecto de este video, consistente con el parámetro de solicitud.
  * `prompt`: la indicación utilizada para generar este video.

En las devoluciones síncronas, el nivel superior también incluirá campos como `started_at`, `finished_at`, `elapsed` (tiempo transcurrido, segundos) y `cost` (cargo de esta vez, unidad Credit).

Solo necesitamos obtener el video generado según la dirección de enlace `video_url` dentro de `data` en el resultado.

El código CURL correspondiente es el siguiente:

```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"
}'
```

El código Python correspondiente es el siguiente:

```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)
```

## Generación de video a partir de imágenes

Si desea generar un video basándose en imágenes de referencia, puede pasar uno o varios enlaces de imágenes en `image_urls` para guiar la generación de video:

```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"
  ]
}
```

## Edición de video / video de referencia (video de entrada, video generado)

Se admite directamente «introducir un video y generar un video nuevo»: pase un enlace de video de referencia en `video_urls` (máximo 1), y **simultáneamente** proporcione al menos una imagen de referencia en `image_urls` (requisito obligatorio del proveedor upstream), y luego use `prompt` para describir el efecto de edición deseado (cambiar el estilo, cambiar el escenario, añadir o eliminar elementos, etc.).

A continuación se muestra un ejemplo real completo: convertir un video de una playa soleada en una escena invernal con abundante nieve, conservando al mismo tiempo la disposición de la playa, las palmeras y la pequeña embarcación. La edición de video tarda más tiempo (aproximadamente 6,5 minutos en este ejemplo), por lo que se envía de forma asíncrona con `async: true`:

```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
}
```

Tras el envío, la interfaz devuelve inmediatamente `task_id`:

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

Después, usa este `task_id` como `id` para consultar mediante sondeo la [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks); una vez completada la tarea, podrás obtener el nuevo video generado (este es el resultado de retorno real de este ejemplo):

```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
  }
}
```

Si se requiere un resultado de mayor resolución, puedes establecer `resolution` en `1080p` (los demás parámetros permanecen sin cambios).

> Nota: Los enlaces de medios de entrada / salida del ejemplo son resultados generados reales. **Los enlaces de videos e imágenes generados por la plataforma tienen un período de conservación y dejarán de ser válidos tras su vencimiento**; descárgalos y guárdalos oportunamente en tu propio almacenamiento después de obtener los resultados.

> Atención: Se permite como máximo 1 video de referencia; además, al proporcionar `video_urls`, debes proporcionar al menos una `image_urls`; de lo contrario, se devolverá el siguiente error de parámetros:

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

## Devolución de llamada asíncrona

La generación de videos requiere cierto tiempo de procesamiento. Si no deseas mantener una conexión larga en espera, puedes pasar `callback_url`; en este caso, la API devolverá inmediatamente `task_id` y, una vez completada la tarea, enviará por POST el resultado final a esta dirección:

```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"
}
```

El resultado devuelto inmediatamente es el siguiente:

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

## Consultar el resultado de la tarea

Si utilizaste la devolución de llamada asíncrona o deseas consultar activamente el estado de la tarea, puedes consultar el estado más reciente y el resultado de la tarea según `task_id` mediante la [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks) (`POST https://api.acedata.cloud/gemini/tasks`). En el cuerpo de la solicitud, pasa el `task_id` devuelto al crear el video como `id`:

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

El resultado devuelto tras completarse la tarea es similar al siguiente; la estructura de `response.data` es coherente con la de la generación síncrona (durante la generación, `state` es `pending` y `video_url` es `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
    }
  }
}
```

## Manejo de errores

Cuando ocurre un problema con la solicitud, la API devolverá el código de error y la descripción correspondientes; los más comunes son los siguientes:

* `400`: Los parámetros de la solicitud son incorrectos; por ejemplo, falta `prompt` o el valor de `aspect_ratio` no es válido.
* `401`: Fallo de autenticación; el token no es válido o no coincide con la API.
* `403`: Saldo insuficiente, o la solicitud fue rechazada porque el prompt activó la revisión de contenido.
* `500`: Error interno del servidor o fallo de generación del servicio ascendente.


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