TL;DR
La API de texto a video de Grok genera videos a partir de un prompt de texto. Llamas a POST /v1/videos/generations, recibes un request_id inmediatamente, luego sondeas GET /v1/videos/{request_id} hasta que el estado sea "done". El modelo es grok-imagine-video, los precios comienzan en $0.05 por segundo a 480p. El SDK de Python de xAI maneja el sondeo automáticamente.
Introducción
xAI generó 1.2 mil millones de videos solo en enero de 2026. Ese fue el primer mes después de lanzar la API de texto a video de Grok el 28 de enero de 2026. El modelo también ocupó el puesto número uno en la clasificación de texto a video de Artificial Analysis ese mismo mes. Esos números importan porque te dicen que la infraestructura está probada a escala.
Esta guía te acompaña en cada paso: realizando tu primera solicitud, sondeando el resultado, ajustando parámetros y escribiendo mejores prompts. También aprenderás a usar imágenes de referencia, extender o editar videos existentes y comprender cuándo la conversión de texto a video es la opción correcta.
¿Qué es la API de texto a video de Grok?
La API de texto a video de Grok es parte del paquete de generación de medios de xAI en https://api.x.ai. Envías un prompt de texto y el modelo grok-imagine-video genera un clip de video corto desde cero. No se requiere una imagen de origen.
La API se sitúa junto a un endpoint de generación de imágenes síncrono (POST /v1/images/generations, modelo grok-imagine-image, $0.02 por imagen). También incluye endpoints para extender o editar videos.
El endpoint de texto a video difiere del endpoint de imagen a video de una manera fundamental: solo proporcionas palabras. El modelo crea la escena, el movimiento y el estilo visual completamente a partir de tu descripción. Consulta la guía de la API de imagen a video de Grok si tienes una imagen de origen y quieres que el modelo la anime en su lugar.
Cómo funciona la generación de texto a video (el patrón asíncrono explicado de forma sencilla)
La mayoría de las llamadas a la API son síncronas. Envías una solicitud, esperas un momento, obtienes tu respuesta. La generación de video tarda de segundos a minutos, por lo que la API utiliza un patrón asíncrono en su lugar.
Así es el flujo:
- Envías una solicitud POST con tu prompt.
- La API devuelve un
request_idinmediatamente (en menos de un segundo). - El video se está generando en los servidores de xAI.
- Sondeas un endpoint GET con ese
request_idrepetidamente. - Cuando el estado cambia de
"processing"a"done", la respuesta incluye una URL de video.
Este patrón es común en las APIs de medios de IA. Mantiene tus conexiones HTTP cortas y te permite verificar el progreso a tu propio ritmo. La parte complicada es que tu frontend necesita manejar el estado intermedio, mostrando un indicador de carga hasta que llegue la URL del video.
Requisitos previos
Antes de escribir cualquier código, necesitas dos cosas:
Una cuenta xAI. Crea una en console.x.ai. También añadirás la facturación allí antes de que tu clave API tenga acceso a la generación.
Una clave API. En la consola de xAI, navega a Claves API y crea una nueva clave. Cópiala en un lugar seguro. La pasarás como un token Bearer en cada encabezado de solicitud.
Establécelo como una variable de entorno para no codificarlo directamente:
export XAI_API_KEY="your_api_key_here"
Opcionalmente, instala el SDK de Python de xAI para la integración más sencilla:
pip install xai-sdk
Tu primera solicitud de texto a video
El endpoint es POST https://api.x.ai/v1/videos/generations. Los únicos campos requeridos son model y prompt.
Usando curl
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": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}'
La respuesta se recibe inmediatamente:
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Ese UUID es tu pase para recuperar el video una vez que esté listo.
Usando Python con la biblioteca requests
import requests
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-video",
"prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers=headers,
json=payload
)
data = response.json()
request_id = data["request_id"]
print(f"Generación iniciada. ID de solicitud: {request_id}")
Sondeo para el resultado del video
Una vez que tengas un request_id, sondea GET /v1/videos/{request_id} hasta que el campo de estado sea igual a "done".
El campo de estado tiene tres valores posibles: - "processing": aún generando - "done": completo, la URL del video está disponible - "failed": algo salió mal
Aquí tienes un bucle de sondeo completo en Python:
import requests
import time
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
"""Sondea hasta que la generación de video esté completa."""
url = f"{BASE_URL}/v1/videos/{request_id}"
for attempt in range(max_attempts):
response = requests.get(url, headers=headers)
data = response.json()
status = data.get("status")
progress = data.get("progress", 0)
print(f"Intento {attempt + 1}: estado={status}, progreso={progress}%")
if status == "done":
return data
elif status == "failed":
raise RuntimeError(f"La generación de video falló: {data}")
time.sleep(interval)
raise TimeoutError(f"Video no listo después de {max_attempts} intentos")
# Flujo de trabajo completo: generar y luego sondear
def generate_video(prompt: str) -> str:
"""Genera un video y devuelve su URL."""
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers={**headers, "Content-Type": "application/json"},
json={"model": "grok-imagine-video", "prompt": prompt}
)
request_id = response.json()["request_id"]
print(f"ID de solicitud: {request_id}")
result = poll_video(request_id)
video_url = result["video"]["url"]
print(f"Video listo: {video_url}")
return video_url
video_url = generate_video(
"A timelapse of a city skyline at sunset transitioning to night, aerial view"
)
Cuando está listo, la respuesta completa del sondeo se ve así:
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/....mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 500000000
}
}
Usando el SDK de Python de xAI
Si prefieres omitir el sondeo manual, el SDK de xAI lo gestiona por ti. El método client.video.generate() se bloquea hasta que el video está listo.
from xai_sdk import Client
import os
client = Client(api_key=os.environ["XAI_API_KEY"])
result = client.video.generate(
model="grok-imagine-video",
prompt="A golden retriever running through autumn leaves in slow motion",
duration=8,
resolution="720p",
aspect_ratio="16:9"
)
print(f"Video URL: {result.video.url}")
print(f"Duration: {result.video.duration}s")
El SDK es el camino más rápido para obtener código funcional. Utiliza el enfoque de solicitudes 'raw' cuando necesites más control sobre la lógica de reintentos, actualizaciones de progreso o intervalos de sondeo personalizados.
Escribiendo prompts efectivos para la generación de video
Tu prompt es la entrada más importante. Un prompt detallado y estructurado produce resultados mucho mejores que uno vago.
Descripción de la escena
Describe el sujeto y el entorno juntos. Sé específico sobre lo que es visible. "Una taza de café de cerámica blanca sobre una mesa de madera junto a una ventana empapada por la lluvia" genera una escena más concreta que "una taza de café".
Movimiento
Dile al modelo qué se mueve y cómo. "La cámara orbita lentamente la taza mientras el vapor se eleva" añade movimiento con una dirección clara. Sin indicaciones explícitas de movimiento, el modelo puede generar un movimiento mínimo o discordante.
Estilo de cámara
Usa terminología de cámara que le darías a un director de fotografía: "primer plano", "plano de seguimiento", "vista de dron aérea", "cámara en mano", "dolly zoom". Estas indicaciones se traducen de forma fiable en el metraje generado.
Iluminación y ambiente
"Hora dorada", "nublado", "iluminado con neones" e "iluminación de estudio de tres puntos" producen apariencias diferentes. Combina la iluminación con el ambiente: "mañana nublada, atmósfera melancólica" le da al modelo una guía tonal más allá de la temperatura del color.
Referencias de estilo
Nombra un estilo visual si tienes uno en mente: "cinemático", "documental", "anime", "stop-motion", "hyperlapse". Combinar dos estilos a menudo produce resultados interesantes.
Estructura de prompt que funciona
Empieza con el sujeto, añade movimiento, describe la cámara, termina con el estilo y el ambiente. Así:
A lone astronaut floats past the International Space Station,
tether drifting behind them. The camera tracks slowly
alongside, showing Earth below. Cinematic, IMAX quality,
warm sunrise light reflecting off the visor.
Controlando la resolución, duración y relación de aspecto
El endpoint de generación acepta varios parámetros opcionales que te permiten controlar las dimensiones de salida, la duración y la calidad.
Duración
"duration": 10
Rango: 1 a 15 segundos. El valor predeterminado es 6 segundos. Los videos más largos cuestan más. Un clip de 10 segundos a 480p cuesta $0.50.
Resolución
"resolution": "720p"
Dos opciones: "480p" (predeterminado) y "720p". Usa 480p para prototipos y pruebas. Usa 720p para la salida de producción donde la calidad es importante.
Relación de aspecto
"aspect_ratio": "9:16"
Relaciones disponibles:
| Relación | Mejor para |
|---|---|
16:9 |
Escritorio, YouTube, presentaciones (predeterminado) |
9:16 |
TikTok, Instagram Reels, móvil |
1:1 |
Feed de Instagram, tarjetas sociales |
4:3 |
Video clásico, presentaciones |
3:4 |
Contenido móvil vertical |
3:2 |
Proporción de foto estándar |
2:3 |
Fotografía vertical |
Ejemplo completo con todos los parámetros
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": "A coastal town at dawn, waves breaking gently on a rocky shore",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Usando imágenes de referencia para guiar el estilo de video
El parámetro reference_images acepta un array de hasta 7 URLs de imágenes. Estas imágenes guían el estilo visual y el contenido del video generado sin convertirse en el sujeto del mismo.
{
"model": "grok-imagine-video",
"prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
"reference_images": [
{"url": "https://example.com/my-style-reference.jpg"},
{"url": "https://example.com/color-palette-reference.jpg"}
]
}
Las imágenes de referencia funcionan mejor cuando comparten una estética consistente. Si proporcionas tres imágenes de diferentes estilos visuales, el modelo intentará reconciliarlas y el resultado podría parecer inconsistente. Usa un conjunto ajustado de imágenes con un aspecto unificado para la guía más fuerte.
Las imágenes de referencia son diferentes del endpoint de imagen a video. Con las imágenes de referencia, tu prompt sigue dirigiendo la escena. Las imágenes influyen en la gradación de color, el estilo de composición y la textura visual. Con imagen a video, la imagen de origen se convierte en el primer fotograma.
Extendiendo y editando videos generados
xAI proporciona dos endpoints adicionales para trabajar con videos que ya has generado.
Extender un video
POST /v1/videos/extensions añade más metraje a un video generado existente. Pasas el request_id del video original y un nuevo prompt para la extensión. Esto es útil para crear secuencias más largas sin alcanzar el límite de 15 segundos en una sola llamada.
Editar un video
POST /v1/videos/edits modifica un video existente basándose en una instrucción de texto. Puedes cambiar el estilo, alterar la escena o aplicar efectos a un clip que ya hayas generado.
Ambos endpoints siguen el mismo patrón asíncrono que el endpoint de generación principal. Devuelven un request_id y sondeas GET /v1/videos/{request_id} para obtener el resultado.
Leyendo el costo de la respuesta de la API
La respuesta completa del sondeo incluye un objeto usage:
"usage": {
"cost_in_usd_ticks": 500000000
}
La unidad son 'USD ticks'. Divide por 10,000,000 para convertir a dólares.
cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Costo: ${cost_in_usd:.4f}")
# Salida: Costo: $0.0500
Referencia de precios
| Resolución | Precio por segundo | Clip de 10 segundos |
|---|---|---|
| 480p | $0.05 | $0.50 |
| 720p | $0.07 | $0.70 |
Un valor de 500000000 ticks equivale a $0.50. Eso es un clip de 10 segundos a 480p.
Controla tus costos registrando cost_in_usd_ticks de cada respuesta completada. Esto te permite construir paneles de uso sin llamar por separado a la API de facturación de xAI.
Cómo probar tu API de video de Grok con Apidog
El patrón de sondeo asíncrono crea un desafío de prueba específico. Tu código frontend necesita manejar tres estados: cargando (mientras se sondea), éxito (URL del video recibida) y error. No puedes probar los tres estados haciendo llamadas API reales, porque cada llamada lleva tiempo y cuesta dinero. Aquí es donde la función Smart Mock de Apidog resuelve el problema directamente.
Caso de uso 1: Smart Mock para desarrollo frontend
Con Smart Mock de Apidog, defines el esquema para ambos endpoints y Apidog devuelve respuestas falsas realistas instantáneamente.
Simular (mock) el endpoint de generación:
En Apidog, crea el endpoint POST /v1/videos/generations en tu proyecto. Define el esquema de respuesta con un único campo de cadena request_id. Smart Mock devolverá un UUID falso automáticamente basado en el patrón del nombre del campo.
Tu respuesta simulada:
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Simular (mock) el endpoint de sondeo:
Crea GET /v1/videos/{request_id} en Apidog. Define el esquema de respuesta completo incluyendo status, video.url, video.duration, progress y usage.cost_in_usd_ticks. Configura una respuesta de Mock Personalizada que devuelva "status": "done" con una URL de MP4 de marcador de posición.
Tu respuesta de sondeo simulada:
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/mock-video-12345.mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 400000000
}
}
Los desarrolladores frontend ahora pueden construir y probar toda la interfaz de usuario del reproductor de video contra este servidor mock. Ven el estado de carga, el estado 'done' y pueden activar el estado de error modificando el mock para que devuelva "status": "failed". No se gastan créditos reales de la API durante el desarrollo.
Caso de uso 2: Escenarios de prueba para el bucle de sondeo
Una vez que tu integración esté construida, usa los Escenarios de Prueba de Apidog para validar automáticamente el flujo completo de generación y sondeo.
Paso 1: Añade la solicitud de generación. Añade POST /v1/videos/generations como primer paso en tu escenario de prueba. En el post-procesador, añade una Variable de Extracción para capturar el request_id del cuerpo de la respuesta usando la expresión JSONPath $.request_id. Almacénala en una variable llamada videoRequestId.
Paso 2: Añade un bucle de sondeo. Añade GET /v1/videos/{{videoRequestId}} como segundo paso. Envuélvelo en un bucle For con una condición de ruptura: response.body.status == "done". Añade un procesador de Espera de 5 segundos entre iteraciones para evitar saturar el límite de tasa.
Paso 3: Afirma el resultado. Después de que el bucle termine, añade un procesador de Aserción a la solicitud GET final. Afirma que $.video.url no está vacío. Esto confirma que el ciclo completo se completó con éxito.
Este escenario de prueba te proporciona una cobertura repetible y automatizada del flujo asíncrono. Ejecútalo en CI para detectar cualquier regresión cuando tu lógica de sondeo cambie.
Texto a video vs imagen a video: cuándo usar cada uno
Ambos modos usan el mismo modelo grok-imagine-video, pero sirven para propósitos diferentes.
Elige texto a video cuando:- Estás generando contenido original a partir de un concepto o guion - Quieres que el modelo tenga control creativo total sobre la composición - Estás construyendo una herramienta de generación de contenido donde los usuarios escriben prompts - No tienes una imagen de origen para empezar
Elige imagen a video cuando:- Tienes una foto de producto, ilustración o activo de marca para animar - Necesitas mantener detalles visuales específicos de una imagen existente - Estás creando animaciones consistentes a partir de una serie de imágenes relacionadas - Quieres animar tu propia obra de arte o fotografía
La distinción clave: texto a video crea una escena desde cero. Imagen a video hace que una imagen existente se mueva. Para una guía completa del enfoque de imagen a video, consulta la guía de la API de imagen a video de Grok.
Para los equipos que construyen productos que ofrecen ambos modos, puedes detectar el tipo de entrada en tiempo de ejecución. Si el usuario sube una imagen, enruta a POST /v1/images/generations (imagen a video). Si solo escriben un prompt, enruta a POST /v1/videos/generations.
Errores comunes y cómo solucionarlos
401 No AutorizadoTu clave API falta, ha caducado o está mal formateada. Verifica que el encabezado de Autorización sea exactamente Bearer YOUR_XAI_API_KEY sin espacios adicionales. Confirma que la clave está activa en la consola de xAI.
429 Demasiadas SolicitudesHas alcanzado un límite de tasa. La API permite 60 solicitudes por minuto y 1 solicitud por segundo. Añade un retraso entre solicitudes. Si estás realizando sondeos, espacia tus llamadas al menos 5 segundos.
estado: "failed" en la respuesta de sondeoLa generación falló. Esto suele significar que el prompt fue rechazado por la moderación de contenido. El campo respect_moderation en la respuesta de sondeo será true si se aplicó moderación. Revisa tu prompt para que sea menos ambiguo o elimina lenguaje potencialmente sensible.
La URL del video devuelve 404Las URLs de los videos generados caducan después de un período de tiempo. Descarga el video a tu propio almacenamiento inmediatamente después de recuperar la URL. No guardes la URL y confíes en que estará disponible días después.
Video vacío o congeladoLos prompts vagos o sin indicaciones de movimiento a veces producen videos con movimiento mínimo. Añade lenguaje de movimiento explícito a tu prompt: describe qué se mueve, en qué dirección y a qué velocidad.
Tiempos de sondeo lentosLos videos de 720p tardan más en generarse que los de 480p. Las duraciones más largas también toman más tiempo. Para el desarrollo y la creación de prototipos, usa "resolution": "480p" y duraciones cortas para acelerar el ciclo de iteración.
Conclusión
La API de texto a video de Grok te ofrece un camino sencillo del texto al video. Envías un prompt, obtienes un request_id, sondeas hasta que esté listo y recuperas tu MP4. El patrón asíncrono es el concepto clave a entender. Una vez que el bucle de sondeo funciona, el resto de los parámetros (duración, resolución, relación de aspecto, imágenes de referencia) son fáciles de ajustar.
Para las compilaciones de producción, añade el seguimiento de costos leyendo cost_in_usd_ticks de cada respuesta completada. Simula ambos endpoints en Apidog durante el desarrollo para que tu equipo frontend no se bloquee esperando generaciones reales. Usa los Escenarios de Prueba para mantener tu lógica de sondeo fiable a medida que tu integración evoluciona.
Descarga Apidog gratis para configurar tu servidor mock y escenarios de prueba para la API de video de Grok.
Preguntas Frecuentes
¿Qué nombre de modelo uso para la generación de texto a video?Usa grok-imagine-video. Este es el campo model requerido en tu solicitud POST a /v1/videos/generations.
¿Cuánto tarda la generación de video?Varía según la duración y la resolución. Los clips cortos de 480p pueden completarse en menos de 30 segundos. Los clips más largos de 720p pueden tardar unos minutos. Sondea cada 5-10 segundos en lugar de saturar el endpoint continuamente.
¿Puedo generar un video de más de 15 segundos?No en una sola solicitud. La duration máxima es de 15 segundos. Para crear videos más largos, genera un clip y luego usa POST /v1/videos/extensions para añadir más metraje.
¿Cómo descargo el video generado?Usa la URL de result.video.url en la respuesta de sondeo completada. Descarga el MP4 a tu almacenamiento inmediatamente. La URL es temporal y caducará.
¿Qué sucede si mi prompt viola la moderación de contenido?El trabajo se completará pero el status será "failed". El campo respect_moderation en la respuesta de sondeo indica que se aplicó moderación. Revisa tu prompt para que sea menos ambiguo o elimina lenguaje potencialmente sensible.
¿Hay un nivel gratuito para la API de video?xAI cobra por segundo de salida generada. No hay un nivel gratuito específicamente para la generación de video. Consulta console.x.ai para ver las ofertas de crédito actuales para nuevas cuentas.
¿En qué se diferencian las reference_images de empezar con una imagen de origen?Las imágenes de referencia guían el estilo visual de una generación de texto a video. Influyen en el aspecto sin convertirse en el sujeto. Una imagen de origen para imagen a video se convierte en el primer fotograma real del video.
¿Cuál es la mejor manera de probar el bucle de sondeo sin gastar créditos?Usa Smart Mock de Apidog para simular tanto los endpoints de generación como los de sondeo. Define los esquemas, establece respuestas mock para los estados "processing" y "done", y tu código de sondeo funcionará sin tocar la API real.