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

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 y guárdelo como respaldo.

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.

📘 Documentación completa: Gemini Videos Generation API →

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:

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

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:

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:

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

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

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

Después, usa este task_id como id para consultar mediante sondeo la Gemini Tasks API; una vez completada la tarea, podrás obtener el nuevo video generado (este es el resultado de retorno real de este ejemplo):

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

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

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

{
  "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 (POST https://api.acedata.cloud/gemini/tasks). En el cuerpo de la solicitud, pasa el task_id devuelto al crear el video como id:

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

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

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

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

Proceso de solicitud

Uso básico

Generación de video a partir de imágenes

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

Devolución de llamada asíncrona

Consultar el resultado de la tarea

Manejo de errores

​Proceso de solicitud

​Uso básico

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

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

​Devolución de llamada asíncrona

​Consultar el resultado de la tarea

​Manejo de errores

Proceso de solicitud

Uso básico

Generación de video a partir de imágenes

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

Devolución de llamada asíncrona

Consultar el resultado de la tarea

Manejo de errores