DEV Community

Cover image for Cómo usar la API de texto a video de Grok: guía completa
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo usar la API de texto a video de Grok: guía completa

TL;DR

La API de texto a video de Grok convierte un prompt de texto en un video. Llama a POST /v1/videos/generations para iniciar la generación y recibe un request_id de inmediato. Luego, haz polling con GET /v1/videos/{request_id} hasta que el estado sea "done". El modelo es grok-imagine-video, con precios desde $0.05 por segundo a 480p. El SDK de Python de xAI automatiza el polling.

Prueba Apidog hoy

Introducción

xAI generó 1.2 mil millones de videos en enero de 2026, el primer mes tras el lanzamiento de la API de texto a video de Grok (28 de enero de 2026). El modelo lideró el ranking de Artificial Analysis de ese mes, demostrando que la infraestructura escala.

Esta guía cubre cómo hacer tu primera solicitud, hacer polling, ajustar parámetros, escribir mejores prompts, usar imágenes de referencia, extender o editar videos y cuándo elegir texto a video.

💡 La API es asíncrona. Tu frontend no puede esperar el video antes de renderizar. Si construyes una UI para generación de video, necesitas mockear el flujo de polling sin gastar créditos. Smart Mock de Apidog permite simular tanto el endpoint de generación como el de polling. Así tu equipo puede avanzar en la UI mientras el backend está en desarrollo. Descarga Apidog gratis para seguir la sección de pruebas más adelante.

¿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ía un prompt de texto y el modelo grok-imagine-video genera un clip de video desde cero, sin requerir imagen de origen.

Comparte espacio con el endpoint de generación de imágenes síncrono (POST /v1/images/generations, modelo grok-imagine-image, $0.02 por imagen) y endpoints para extender o editar videos.

La diferencia clave con imagen a video: aquí solo envías texto, y el modelo crea la escena, movimiento y estilo desde tu descripción. Si tienes una imagen de origen y quieres animarla, consulta la guía de la API de imagen a video de Grok.

Cómo funciona la generación de texto a video (patrón asíncrono)

La mayoría de APIs esperan la respuesta antes de continuar. Para video, la generación puede tardar de segundos a minutos, así que Grok usa un flujo asíncrono:

  1. Envía un POST con tu prompt.
  2. Recibes un request_id (en menos de 1 segundo).
  3. El video se genera en los servidores de xAI.
  4. Haz polling con GET usando ese request_id repetidamente.
  5. Cuando el estado sea "done", la respuesta trae la URL del video.

Este patrón mantiene conexiones HTTP cortas y permite verificar progreso a tu ritmo. Tu frontend debe manejar el estado intermedio y mostrar un loading hasta que llegue la URL.

Requisitos previos

Antes de programar:

  • Cuenta xAI: Regístrate en console.x.ai. Agrega facturación para habilitar la generación.
  • Clave API: En la consola, ve a Claves API y crea una. Guárdala de forma segura. Úsala como token Bearer en el header de cada request. 
export XAI_API_KEY="your_api_key_here"
Enter fullscreen mode Exit fullscreen mode

Opcional: instala el SDK de Python de xAI para integración rápida:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Captura de pantalla de la consola de xAI mostrando la generación de claves API

Tu primera solicitud de texto a video

El endpoint es POST https://api.x.ai/v1/videos/generations. Solo necesitas los campos 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Respuesta inmediata:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

Ese UUID sirve para consultar el video cuando esté listo.

Usando Python y 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}")
Enter fullscreen mode Exit fullscreen mode

Sondeo para el resultado del video

Con tu request_id, haz polling a GET /v1/videos/{request_id} hasta que el estado sea "done".

Estados posibles:

  • "processing": generando
  • "done": completo, URL disponible
  • "failed": error

Bucle de polling 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"
)
Enter fullscreen mode Exit fullscreen mode

Respuesta de polling cuando está listo:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}
Enter fullscreen mode Exit fullscreen mode

Usando el SDK de Python de xAI

El SDK gestiona el polling automáticamente. El método client.video.generate() espera 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")
Enter fullscreen mode Exit fullscreen mode

El SDK es la vía más rápida para prototipos funcionales. Usa requests manuales solo si necesitas controlar lógica de reintentos o intervalos personalizados.

Escribiendo prompts efectivos para video

El prompt es la clave para resultados óptimos. Sé específico y estructurado.

Descripción de la escena

Incluye sujeto y entorno:

"Una taza de café de cerámica blanca sobre una mesa de madera junto a una ventana empapada por la lluvia"

Movimiento

Indica qué se mueve y cómo:

"La cámara orbita lentamente la taza mientras el vapor se eleva"

Estilo de cámara

Usa términos de cine:

"primer plano", "plano de seguimiento", "vista de dron aérea", "cámara en mano", "dolly zoom"

Iluminación y ambiente

Ejemplos útiles:

"hora dorada", "nublado", "iluminado con neones", "atmósfera melancólica"

Referencias de estilo

Nombra estilos visuales:

"cinemático", "documental", "anime", "stop-motion", "hyperlapse"

Estructura recomendada de prompt

Empieza con el sujeto, añade movimiento, describe la cámara, termina con el estilo y el ambiente:

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.
Enter fullscreen mode Exit fullscreen mode

Controlando resolución, duración y relación de aspecto

El endpoint acepta parámetros opcionales para controlar salida, duración y calidad.

Duración 

"duration": 10
Enter fullscreen mode Exit fullscreen mode

Rango: 1–15 segundos. Default: 6s. Más segundos = mayor costo.

Resolución 

"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

Opciones: "480p" (default), "720p". Usa 480p para pruebas y 720p para producción.

Relación de aspecto 

"aspect_ratio": "9:16"
Enter fullscreen mode Exit fullscreen mode

Relaciones válidas:

Relación Uso recomendado
16:9 Escritorio, YouTube (default)
9:16 TikTok, Instagram Reels, móvil
1:1 Instagram feed, tarjetas sociales
4:3 Video clásico, presentaciones
3:4 Contenido móvil vertical
3:2 Foto estándar
2:3 Fotografía vertical

Ejemplo completo 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Usando imágenes de referencia para guiar el estilo

El parámetro reference_images acepta hasta 7 URLs de imágenes. No se usan como sujeto, sino para guiar el estilo visual del video.

{
  "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"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Usa imágenes de referencia con estética coherente para influir fuertemente en el resultado. No es lo mismo que imagen a video: aquí el prompt sigue dirigiendo la escena.

Extendiendo y editando videos generados

xAI ofrece dos endpoints extra:

Extender un video

POST /v1/videos/extensions agrega más duración a un video ya generado. Envía el request_id original y un nuevo prompt para continuar la animación.

Editar un video

POST /v1/videos/edits modifica un video existente según una instrucción de texto: cambia el estilo, efectos o la escena.

Ambos endpoints usan el mismo patrón asíncrono: devuelven un request_id y haces polling con GET /v1/videos/{request_id}.

Leyendo el costo en la respuesta de la API

El campo usage en la respuesta incluye el costo en ticks:

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

Divide entre 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}")
# Ejemplo de salida: Costo: $0.0500
Enter fullscreen mode Exit fullscreen mode

Referencia de precios

Resolución Precio por segundo 10s de video
480p $0.05 $0.50
720p $0.07 $0.70

Controla tus costos leyendo el campo cost_in_usd_ticks de cada respuesta.

Cómo probar tu API de video de Grok con Apidog

El polling asíncrono requiere que tu frontend maneje tres estados: cargando, éxito y error. Simular este flujo con la API real es costoso y lento. Smart Mock de Apidog lo resuelve simulando ambos endpoints.

Configuración de Apidog Smart Mock para la API de video de Grok

Caso de uso 1: Smart Mock para desarrollo frontend

Con Smart Mock de Apidog:

  • Simula POST /v1/videos/generations: Define el esquema de respuesta con un campo request_id tipo string. Apidog genera un UUID falso automáticamente.

Ejemplo de respuesta mock:

  {
    "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
  }
Enter fullscreen mode Exit fullscreen mode
  • Simula GET /v1/videos/{request_id}: Define el esquema completo con status, video.url, video.duration, progress y usage.cost_in_usd_ticks. Configura una respuesta mock personalizada con "status": "done" y una URL de MP4 genérica.

Ejemplo de respuesta mock:

  {
    "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
    }
  }
Enter fullscreen mode Exit fullscreen mode

Los desarrolladores frontend pueden construir y probar toda la UI del reproductor de video contra este servidor mock. Pueden simular estados de carga, éxito y error modificando el mock. No se gastan créditos reales de la API.

Caso de uso 2: Escenarios de prueba para el bucle de polling

Con los Escenarios de Prueba de Apidog automatiza la validación:

Paso 1: Añade la solicitud POST /v1/videos/generations. Usa una Variable de Extracción para capturar el request_id con JSONPath ($.request_id).

Paso 2: Añade el GET /v1/videos/{{videoRequestId}} en un bucle For, con condición de salida: response.body.status == "done". Añade un delay de 5s entre iteraciones.

Paso 3: Agrega una aserción para que $.video.url no esté vacío en la última respuesta.

Esto asegura una cobertura repetible del flujo asíncrono y ayuda a detectar regresiones en tu lógica de polling.

Texto a video vs imagen a video: ¿cuándo usar cada uno?

Ambos usan grok-imagine-video, pero tienen usos distintos:

Texto a video:

  • Genera contenido original desde un prompt/concepto.
  • El modelo tiene control creativo total.
  • Útil para herramientas donde el usuario solo escribe un prompt.
  • No tienes una imagen fuente.

Imagen a video:

  • Tienes una imagen/ilustración/foto de producto a animar.
  • Necesitas preservar detalles visuales exactos.
  • Quieres animaciones consistentes desde varias imágenes.

Texto a video crea la escena desde cero; imagen a video anima una imagen existente. Para una guía completa de imagen a video, revisa la guía de la API de imagen a video de Grok.

En productos que soportan ambos modos, decide en tiempo de ejecución: si el usuario sube una imagen, usa /v1/images/generations; si solo escribe texto, usa /v1/videos/generations.

Errores comunes y cómo solucionarlos

  • 401 No Autorizado: Falta la clave API, está caducada o mal formateada. Verifica el header Authorization: Bearer YOUR_XAI_API_KEY y que la clave esté activa.
  • 429 Too Many Requests: Excediste el rate limit (60 req/min, 1 req/seg). Espacia tus llamadas, especialmente en polling (mínimo 5s entre requests).
  • status: "failed" en polling: El prompt fue rechazado por moderación. El campo respect_moderation será true. Revisa y ajusta el prompt.
  • La URL del video arroja 404: Las URLs caducan. Descarga el video apenas recibas la URL.
  • Video vacío o congelado: Prompts vagos o sin instrucciones de movimiento. Sé explícito sobre qué se mueve y cómo.
  • Polling lento: 720p y duraciones largas tardan más. Usa 480p y clips cortos para desarrollo y prototipado.

Conclusión

La API de texto a video de Grok es directa: envías un prompt, recibes un request_id, haces polling y descargas tu MP4. Domina el patrón asíncrono y el resto (duración, resolución, relación de aspecto, imágenes de referencia) es parametrizable.

Para producción, monitorea el costo leyendo cost_in_usd_ticks tras cada generación. Simula endpoints en Apidog para que el frontend avance sin bloqueos. Usa Escenarios de Prueba para mantener fiable tu lógica de polling.

Descarga Apidog gratis para configurar mocks 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 como valor de model en tu POST a /v1/videos/generations.

¿Cuánto tarda la generación de video?

Depende de duración y resolución. 480p corto: <30s. 720p largo: varios minutos. Haz polling cada 5-10s.

¿Puedo generar videos de más de 15 segundos?

No en una sola solicitud. duration máximo: 15s. Para videos más largos, encadena clips y usa POST /v1/videos/extensions.

¿Cómo descargo el video generado?

Usa la URL result.video.url del polling. Descarga el MP4 de inmediato; la URL caduca.

¿Qué sucede si mi prompt viola la moderación de contenido?

El estado será "failed". respect_moderation indicará si hubo moderación. Ajusta el prompt.

¿Hay un nivel gratuito para la API de video?

No hay free tier específico para video. Consulta console.x.ai para créditos de bienvenida.

¿En qué se diferencian las reference_images de una imagen de origen?

reference_images guían el estilo visual del video generado desde texto. Una imagen de origen en imagen a video se convierte en el primer fotograma real.

¿Cómo pruebo el bucle de polling sin gastar créditos?

Usa Smart Mock de Apidog para simular los endpoints de generación y polling. Define los esquemas y estados mock para cubrir todos los casos en tus test.

Top comments (0)