Saltar al contenido principal
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:
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:
El código Python correspondiente es el siguiente:

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:

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

Se admite directamente «introducir un video y generar un video nuevo»: proporcione un enlace a un video de referencia (máximo 1) en video_urls y, al mismo tiempo, incluya al menos una imagen de referencia en image_urls; después, use prompt para describir el efecto de edición deseado (cambiar el estilo, cambiar la escena, 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 fuertes nevadas, conservando al mismo tiempo la distribución de la playa, las palmeras y el bote. La edición de video tarda bastante (unos 6,5 minutos en este ejemplo), por lo que se envía de forma asíncrona mediante async: true:
Tras el envío, la API devuelve inmediatamente task_id:
Después, use ese task_id como id para consultar la API de Gemini Tasks. Cuando la tarea finalice, podrá obtener el nuevo video generado (este es el resultado real devuelto por este ejemplo):
Si necesita un resultado en mayor resolución, puede establecer resolution en 1080p (sin cambiar los demás parámetros).
Aviso: los enlaces de medios de entrada/salida de los ejemplos son resultados generados reales. Los enlaces de video e imagen generados por la plataforma tienen un período de conservación y dejarán de ser válidos al vencer; descárguelos y guárdelos en su propio almacenamiento tan pronto como obtenga los resultados.
Atención: se permite un máximo de 1 video de referencia; además, al proporcionar video_urls, debe proporcionar al menos una imagen image_urls; de lo contrario, se devolverá el siguiente error de parámetros:

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:
El resultado devuelto inmediatamente es el siguiente:

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

Manejo de errores

Cuando haya un problema con la solicitud, la API devolverá el código de error y la descripción correspondientes. Los errores 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: error de autenticación; el token no es válido o no coincide con la API.
  • 403: saldo insuficiente, o la solicitud fue rechazada por la moderación de contenido debido al texto de la instrucción.
  • 500: excepción del servicio o error de generación.