Ir al contenido principal
Español— Elegir un idioma
Menú

Endpoint /v1/videos/generations: Tu primer vídeo

Lección 1 de 12 Actualizado el 3 de noviembre de 2026 Intermedio
En esta página
  1. Generar un vídeo a partir de texto
  2. Estructura de la solicitud
  3. Una primera llamada de extremo a extremo
  4. Audio, por defecto
  5. Puntos clave

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 -lite y grok-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ámetro size que 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.

1-15 s
Duración por vídeo
1080p
Resolución máxima
desde 0,02 $
Por segundo generado
9
Relaciones de aspecto disponibles

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ómica grok-imagine-video-1.5-lite, recomendada por xAI para vídeos sencillos; o grok-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), 720p o 1080p; esta última se renderiza de forma nativa con grok-imagine-video-1.5 en texto a vídeo e imagen a vídeo, se obtiene mediante remuestreo desde 720p en la versión -lite y está ausente en grok-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, con grok-imagine-video-1.5, su versión -lite o grok-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_id para 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": false produce un vídeo sin sonido.