Endpoint /v1/videos/generations: Tu primer vídeo
En esta página
Actualizado el 3 de noviembre de 2026 según la documentación de vídeo de xAI: hay tres modelos de vídeo disponibles (
grok-imagine-video-1.5, su versión-liteygrok-imagine-video), la resolución alcanza hasta 1080p en los modelos 1.5, los vídeos incluyen una pista de audio por defecto (generate_audio), los límites de tasa se cuentan en solicitudes por segundo y el parámetrosizeque presentaba la versión antigua no aparece en la referencia de la API. Fuentes: Generación de vídeo · Precios.
Generar un vídeo a partir de texto
La API de xAI expone un endpoint dedicado para vídeo, POST /v1/videos/generations, que transforma una descripción escrita en una secuencia animada utilizando uno de los tres modelos de Grok Imagine Video. Piensa en ello como un estudio bajo demanda: describes una escena, el modelo la pone en movimiento y recuperas un archivo MP4 listo para editar. Clips promocionales, visualizaciones de conceptos, animaciones ilustrativas; todos estos casos de uso pasan por este mismo endpoint, así que lo diseccionaremos primero.
El ejemplo anterior te da una idea del resultado esperado. Antes de escribir tu primera solicitud, ten en cuenta los cuatro límites que enmarcan todo lo que produces con estos modelos.
Estructura de la solicitud
El cuerpo de la solicitud es un objeto JSON de una simplicidad reconfortante. Declaras el modelo, escribes tu indicación (prompt) y enmarcas el resultado con tres parámetros de formato.
{
"model": "grok-imagine-video",
"prompt": "Un delfín saltando al atardecer",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Aquí tienes el significado exacto de cada campo:
- model:
grok-imagine-video-1.5, el más nuevo; su versión económicagrok-imagine-video-1.5-lite, recomendada por xAI para vídeos sencillos; ogrok-imagine-video, la generación anterior, que aún se usa en los ejemplos de este curso. - prompt: tu descripción textual de la escena deseada.
- duration: duración en segundos, entre 1 y 15 (8 por defecto).
- aspect_ratio: relación de aspecto de la imagen (16:9 por defecto, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2).
- resolution:
480p(predeterminado),720po1080p; esta última se renderiza de forma nativa congrok-imagine-video-1.5en texto a vídeo e imagen a vídeo, se obtiene mediante remuestreo desde 720p en la versión-litey está ausente engrok-imagine-video, que se detiene en 720p.
Dos puntos merecen énfasis ahora mismo. El modelo grok-imagine-video cuesta 0,050 $ por segundo de vídeo generado (0,08 $ para grok-imagine-video-1.5, 0,02 $ para su versión -lite, a fecha de 3 de noviembre de 2026): una secuencia de cinco segundos te cuesta, por tanto, 0,25 $ con el primero, independientemente de cuántos intentos hayas necesitado para llegar ahí. Y el límite de tasa se cuenta en solicitudes por segundo, dependiendo del nivel de tu equipo: 10 en el nivel de entrada para modelos de vídeo, un margen cómodo para el uso normal, que se convierte en una restricción cuando lanzas lotes masivos.
Lo más importante es que la generación es asíncrona. Tu llamada POST no devuelve un vídeo: devuelve un request_id, y corresponde a ti sondear el estado hasta que el archivo esté listo. Este mecanismo de sondeo es el tema de una lección completa más adelante en el curso; por ahora, solo recuerda que la respuesta inmediata es un acuse de recibo, no un resultado.
Una primera llamada de extremo a extremo
Pasemos a la práctica con curl. La siguiente solicitud pide una secuencia de cinco segundos en 720p y formato apaisado.
curl -X POST "https://api.x.ai/v1/videos/generations" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video",
"prompt": "Un gato jugando con un ovillo de lana en un salón luminoso",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'
La respuesta cabe en una línea:
{
"request_id": "vid_abc123def456"
}
Guarda bien este identificador. Es tu única forma de recuperar el vídeo una vez finalizada la generación, y una aplicación que lo pierda habrá pagado por una generación que nunca recuperará. En un servicio real, lo registras antes incluso de empezar el sondeo.
Audio, por defecto
Un vídeo generado incluye una pista de audio por defecto; con grok-imagine-video-1.5 y su versión -lite, el habla está sincronizada con el movimiento de los labios. Para un vídeo sin sonido, destinado por ejemplo a un fondo de sitio web o para edición donde añadirás tu propia música, añade "generate_audio": false a la solicitud.
Para enmarcar la salida, sin embargo, la API solo conoce la relación de aspecto (aspect_ratio) y la definición (resolution): la referencia de la API no proporciona ningún parámetro de tamaño en píxeles. En imagen a vídeo, la relación de aspecto de salida sigue siempre la de la imagen de origen.
Puntos clave
- El endpoint es
POST /v1/videos/generations, congrok-imagine-video-1.5, su versión-liteogrok-imagine-video. - La duración va de 1 a 15 segundos (8 por defecto); la resolución, de 480p a 1080p (máximo 720p con
grok-imagine-video). - El precio se cuenta por segundo generado: 0,020 $ (
-lite), 0,050 $ (grok-imagine-video) o 0,080 $ (grok-imagine-video-1.5). - La generación es asíncrona: recibes un
request_idpara sondear después. - Hay nueve relaciones de aspecto disponibles para adaptarse a todos los formatos.
- Se genera una pista de audio por defecto;
"generate_audio": falseproduce un vídeo sin sonido.