Saltar al contenido principal
Este documento presentará la integración de la API de Generación de Videos de Grok, que puede generar videos de Grok Imagine (xAI) a través de la entrada de texto, imágenes y, opcionalmente, imágenes de referencia.

Proceso de Solicitud

Para usar la API de Generación de Videos de Grok, primero dirígete a Ace Data Cloud Console para obtener tu Token de API, que debes guardar para uso futuro. Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual. Un Token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno para cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito se agota, puedes recargar el saldo general en la consola.
📘 Documentación completa: Grok Videos Generation API →

Descripción del modelo

Los siguientes cuatro modelos públicos pueden seleccionarse mediante model. Sus capacidades específicas y métodos de facturación son los siguientes:
  • grok-imagine-video-1.5-fast:reverse (predeterminado): admite generación de vídeo a partir de texto (solo se pasa prompt) y generación de vídeo a partir de imágenes (se pasa image_url), con duraciones de 6 a 30 segundos. La facturación se realiza por tramos de duración y es la opción más económica.
  • grok-imagine-video:reverse: admite generación de vídeo a partir de texto e imágenes, con duraciones de 1 a 15 segundos, y se factura por segundos de salida.
  • grok-imagine-video:official: admite generación de vídeo a partir de texto e imágenes, con duraciones de 1 a 15 segundos, y se factura por segundos de salida, con mayor calidad de imagen.
  • grok-imagine-video-1.5:official: solo admite generación de vídeo a partir de imágenes; es obligatorio proporcionar image_url. La duración es de 1 a 15 segundos, admite hasta 1080p y se factura por segundos de salida.

Uso Básico

Primero, comprende la forma básica de uso, ingresando el texto de aviso prompt, el modelo model y otros parámetros, podrás generar el video correspondiente. Aquí podemos ver que hemos configurado los Encabezados de Solicitud, que incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
Además, se ha configurado el Cuerpo de Solicitud, que incluye:
  • prompt: texto que describe el contenido del video que deseas generar. Obligatorio al hacer videos generados a partir de texto; opcional al pasar image_url.
  • model: el modelo para generar el video, puede ser grok-imagine-video-1.5-fast:reverse (predeterminado), grok-imagine-video:reverse, grok-imagine-video:official o grok-imagine-video-1.5:official.
  • image_url: enlace de la imagen de entrada para videos generados a partir de imágenes. Obligatorio cuando model es grok-imagine-video-1.5:official.
  • reference_image_urls: array de enlaces de imágenes de referencia opcionales, utilizados para guiar el estilo o contenido del video.
  • aspect_ratio: relación de aspecto del video generado, puede ser 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution: resolución de salida, puede ser 480p (predeterminado), 720p o 1080p.
  • duration: duración del video generado (segundos). grok-imagine-video-1.5-fast:reverse tiene un rango de 6 a 30, los demás modelos tienen un rango de 1 a 15, predeterminado 6. Se recomienda usar 6 segundos o 10 segundos, estas dos duraciones estándar son relativamente estables.
  • callback_url: dirección de callback asíncrona, al configurarla, la API devolverá inmediatamente task_id, y cuando la tarea esté completa, enviará el resultado a esa dirección.
  • async: opcional, si se establece en true, la interfaz devolverá inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego podrás consultar el resultado a través de la interfaz de consulta de tareas correspondiente.
Haz clic en el botón “Try” para realizar pruebas, y el resultado obtenido será similar al siguiente:
El resultado devuelto tiene varios campos, que se describen a continuación:
  • success: indica si la solicitud de generación de video fue exitosa.
  • task_id: ID de la tarea de generación de video.
  • trace_id: ID de seguimiento de la solicitud, utilizado para resolver problemas.
  • data: lista de resultados de video generados.
    • id: identificador único del video generado.
    • video_url: dirección del enlace del video generado.
    • state: estado de la tarea de generación de video, puede ser pending / succeeded / failed.
Solo necesitamos obtener el video generado a través de la dirección del enlace video_url en data. El código CURL correspondiente es el siguiente:
El código Python correspondiente es el siguiente:

Videos Generados a partir de Imágenes

Si deseas generar un video basado en una imagen de entrada, puedes pasar image_url. Al usar grok-imagine-video-1.5:official, este campo debe ser proporcionado:

Guía de Imágenes de Referencia

Si deseas utilizar una o más imágenes de referencia para guiar el estilo o contenido del video, puedes pasar un array de enlaces de imágenes en reference_image_urls:

Callback Asíncrono

La generación de video requiere un tiempo de procesamiento. Si no desea mantener una conexión larga esperando, puede pasar callback_url, en este caso, la API devolverá inmediatamente task_id, y una vez que la tarea esté completa, enviará el resultado final a esa dirección:
El resultado devuelto inmediatamente es el siguiente:

Consulta de resultados de tareas

Si se utilizó una devolución de llamada asíncrona o se desea consultar activamente el estado de la tarea, se puede consultar el estado y resultado más reciente de la tarea a través de Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) según task_id.

Información sobre la facturación

El método de facturación de este servicio está determinado por model:
  • grok-imagine-video-1.5-fast:reverse: facturación por tramos de duración, independientemente de la resolución; 6–10 segundos, 11–20 segundos y 21–30 segundos corresponden a diferentes niveles de precio.
  • grok-imagine-video:reverse: facturación por «segundos de salida»; precio total = precio unitario × duration.
  • grok-imagine-video:official y grok-imagine-video-1.5:official: facturación por «segundos de salida»; cuanto mayor sea la resolución, mayor será el precio unitario. Los modelos oficiales se cobrarán incluso si falla la moderación del contenido.
Los precios unitarios específicos están sujetos a la página de precios. Las solicitudes fallidas no se cobran ni consumen la cuota gratuita.

Manejo de errores

Cuando hay un problema con la solicitud, la API devolverá el código de error correspondiente y la descripción, los más comunes son:
  • 400: Parámetros de solicitud incorrectos, por ejemplo, falta prompt en video generado, o falta image_url en grok-imagine-video-1.5:official, o duration fuera de rango (para grok-imagine-video-1.5-fast:reverse es 6–30, para otros modelos es 1–15).
  • 401: Fallo de autenticación, token inválido o no coincide con la API.
  • 403: Saldo insuficiente, o la palabra clave activó la revisión de contenido y fue rechazada.
  • 429: Solicitudes demasiado frecuentes, por favor intente de nuevo más tarde.
  • 500: Fallo en la generación de video o error en el servicio.