Cómo Usar la API de Grok de Imagen a Video (Guía Paso a Paso)

En resumen

La API de imagen a video de Grok utiliza el modelo grok-imagine-video para animar imágenes estáticas y convertirlas en videoclips. El flujo es asíncrono: envía (POST) la URL de la imagen, un prompt y parámetros opcionales a https://api.x.ai/v1/videos/generations, recibe un request_id inmediato y realiza polling con GET /v1/videos/{request_id} hasta que el status sea "done". Los videos pueden durar entre 1 y 15 segundos. El costo inicia en $0.05 por segundo para 480p.

Prueba Apidog hoy

Introducción

El 28 de enero de 2026, xAI lanzó el modelo grok-imagine-video para acceso público mediante API. En el primer mes, generó 1,200 millones de videos y lideró el ranking de texto a video de Artificial Analysis. La conversión imagen a video permite animar una foto con un prompt descriptivo, entregando un videoclip MP4 listo para descargar.

La integración es asíncrona: la API responde con un request_id, pero el proceso concluye cuando gestionas correctamente los estados "processing", "done" y "failed" durante el polling bajo condiciones reales.

Los Escenarios de Prueba de Apidog permiten automatizar este flujo: POST para generar, extracción de request_id, polling hasta status == "done", y aserción de que la URL del video es válida. Utiliza Apidog para automatizar y validar este flujo de pruebas.

¿Qué es la API de imagen a video de Grok?

La API de imagen a video de Grok es parte del producto de generación de video de xAI. Bajo el modelo grok-imagine-video, acepta una imagen como primer fotograma y, junto a un prompt, genera movimiento natural para animar la escena.

Endpoint principal:

POST https://api.x.ai/v1/videos/generations

Autenticación:

Authorization: Bearer YOUR_XAI_API_KEY

Obtén tu clave en la consola de xAI. El mismo endpoint soporta generación texto a video (sin parámetro image), extensiones y ediciones de video.

Cómo funciona el proceso de imagen a video

El parámetro image define el primer fotograma. El modelo parte de tu imagen y, usando el prompt, predice la animación subsecuente.

Ejemplo:

• Imagen: Foto de un lago al amanecer.
• Prompt: "suaves ondas se extienden por el agua mientras la niebla matutina se dispersa"
• El primer fotograma es tu imagen, los siguientes animan agua y niebla según el prompt.

Cuándo usar imagen a video:

• Tienes fotos de productos, paisajes o retratos que quieres animar.
• Requieres identidad visual consistente en el primer fotograma.
• Deseas movimiento anclado a una escena específica.

Cuándo usar texto a video:

• No tienes imagen de referencia.
• Prefieres que el modelo componga la escena.
• Prioridad en velocidad de iteración sobre precisión visual.

Prerrequisitos

Antes de la primera llamada, asegúrate de contar con:

1. Cuenta de xAI en console.x.ai
2. Clave API de la consola (usa variable de entorno, nunca hardcode).
3. Python 3.8+ o Node.js 18+ (ejemplos en ambos).
4. URL de imagen pública o imagen codificada en base64 (data URI).

Configura tu clave API:

export XAI_API_KEY="your_key_here"

Instala el SDK de Python si quieres cliente de alto nivel:

pip install xai-sdk

Para llamadas HTTP directas, basta con requests (Python) o fetch/axios (Node.js).

Realizando tu primera solicitud de imagen a video

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": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Respuesta:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

El video se genera asíncronamente. Haz polling con el request_id.

Usando Python (solicitudes directas)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")

Usando una imagen base64

Si la imagen es local, conviértela a data URI:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

Consultando (polling) el resultado

La generación es asíncrona. Consulta el estado con:

GET https://api.x.ai/v1/videos/{request_id}

Estados posibles:

Estado	Significado
"processing"	El video está renderizándose
"done"	El video está listo; la URL viene en respuesta
"failed"	Hubo un error

Respuesta ejemplo:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

Ciclo completo de polling en Python

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# Uso
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

Importante: Mantén el intervalo de polling ≥5 segundos. El límite es 60 solicitudes/minuto (1/seg).

Usando el SDK de Python de xAI

El paquete xai-sdk abstrae el polling. client.video.generate() envía el trabajo y espera el video listo:

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")

Usa el SDK para código más limpio. El enfoque manual ofrece mayor control sobre intervalos y reintentos.

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

La API permite controlar el formato de salida desde el request.

Duración

duration: Entero de 1 a 15 segundos (default: 6).

"duration": 10

El costo escala linealmente con la duración.

Resolución

Valor	Descripción
"480p"	Default; menor costo y mayor velocidad
"720p"	Máxima calidad; $0.07/seg vs $0.05/seg

"resolution": "720p"

Relación de aspecto

aspect_ratio define las dimensiones finales.

Valor	Caso de uso
"16:9"	Default; paisaje
"9:16"	Vertical móvil
"1:1"	Cuadrado/redes
"4:3"	Presentación clásica
"3:4"	Retrato
"3:2"	Fotografía estándar
"2:3"	Retrato alto

Por defecto, coincide con el aspecto de la imagen fuente. Define explícitamente para forzar recorte.

---

Usando imágenes de referencia para la guía de estilo

El parámetro reference_images es complementario a image.

• image: Es el primer fotograma real del video.
• reference_images: Hasta 7 imágenes para guiar estilo o contexto visual (no aparecen literalmente).

Ejemplo:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

Las imágenes de referencia pueden usarse también en generación texto a video.

Extendiendo y editando videos

La API soporta dos operaciones adicionales:

Extendiendo un video

POST /v1/videos/extensions permite agregar segundos a un video existente (máximo 15s por llamada).

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

El polling funciona igual que en la generación inicial.

Editando un video

POST /v1/videos/edits aplica prompts para modificar un video existente.

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

Ambos endpoints son asíncronos y requieren polling.

Desglose de precios: cuánto cuesta un video de 10 segundos

Componente	Costo
Imagen de entrada	$0.002 / imagen
Salida 480p	$0.05 / segundo
Salida 720p	$0.07 / segundo

Ejemplo 10s a 720p:

• Imagen: $0.002
• Salida: 10 × $0.07 = $0.70
• Total: $0.702

Ejemplo 6s a 480p:

• Imagen: $0.002
• Salida: 6 × $0.05 = $0.30
• Total: $0.302

Cada POST genera un cargo de imagen, incluso si la URL es la misma. El texto a video omite el cargo por imagen.

Cómo probar tu integración de la API de video de Grok con Apidog

Para validar la integración asíncrona, necesitas comprobar:

1. El POST devuelve un request_id.
2. El polling gestiona correctamente el estado "processing".
3. El resultado final tiene status == "done" y una URL de video válida.

Con los Escenarios de Prueba de Apidog, automatiza el flujo completo:

Paso 1: Crear un nuevo Escenario de Prueba

En Apidog, entra al módulo de Pruebas y crea un escenario llamado "Grok image-to-video async flow."

Paso 2: Añadir la solicitud de generación

Agrega un paso POST:

• URL: https://api.x.ai/v1/videos/generations
• Método: POST
• Cabecera: Authorization: Bearer {{xai_api_key}}
• Cuerpo (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

Paso 3: Extraer el request_id

Agrega un procesador de Extraer Variable:

• Nombre: video_request_id
• Fuente: cuerpo de respuesta
• Método: JSONPath
• Expresión: $.request_id

Paso 4: Construir el ciclo de polling

Agrega un bucle For con:

• Solicitud GET a https://api.x.ai/v1/videos/{{video_request_id}}
• Cabecera: Authorization: Bearer {{xai_api_key}}
• Extrae video_status con JSONPath: $.status
• Espera 5000ms tras cada polling para no saturar el rate limit
• Condición de ruptura: {{video_status}} == "done"

Paso 5: Afirmar la URL del video

Tras el bucle, realiza un GET final y agrega una aserción:

• Campo: $.video.url
• Condición: No vacío

Esto confirma la generación exitosa y disponibilidad del video.

Para detalles sobre pruebas CI/CD y patrones avanzados, consulta la guía dedicada de Apidog.

Ejecución del escenario:

Haz clic en Ejecutar en la vista del escenario. Apidog ejecuta el POST, extrae el request_id, realiza polling y valida la aserción. Puedes integrarlo a pipelines con la CLI:

apidog run --scenario grok-video-async-flow --env production

Errores comunes y soluciones

401 No autorizado

• Revisa el header: Authorization: Bearer YOUR_XAI_API_KEY
• Asegúrate de que la clave está activa.

422 Entidad no procesable

• Verifica que el body tenga model, prompt no vacío e imagen accesible.

URL de imagen no accesible

• Usa URLs públicas o data URI base64.

El estado permanece en "processing"

• Si supera 10 minutos, reintenta. No hay timeout explícito.

Rate limit (429)

• No superes 60 solicitudes/minuto o 1/segundo. Añade sleeps.

Carga base64 rechazada

• Usa el prefijo MIME correcto: data:image/jpeg;base64, o data:image/png;base64,.

Desajuste de relación de aspecto

• Si el aspect_ratio difiere mucho del original, puede haber recortes. Alinea ambos para resultados óptimos.

Conclusión

La API de imagen a video de Grok permite transformar fotos en clips animados de forma programática. Envía la imagen y el prompt, recibe un request_id, haz polling hasta finalizar y descarga el MP4. El modelo grok-imagine-video lideró la generación de video AI en 2026 con más de mil millones de videos en un mes.

El mayor fallo en integraciones es una gestión incorrecta del polling. Automatiza pruebas en Apidog con extracción de variables, ciclo de polling y aserción final para robustecer tu pipeline.

Comienza a construir tu integración con Apidog de forma gratuita. No se requiere tarjeta de crédito.

Preguntas Frecuentes

¿Qué nombre de modelo uso para imagen a video de Grok?

grok-imagine-video, pásalo en el campo model del body.

¿Diferencia entre image y reference_images?

image define el primer fotograma real. reference_images guía estilo, pero no aparece literalmente. Puedes usar ambos.

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

Varía por duración y resolución. Un 480p de 6s: 1-3 minutos. Un 720p de 15s: 4-8 minutos. Haz polling cada 5 segundos.

¿Puedo usar archivo local como imagen?

Sí, conviértelo a data URI base64: data:image/jpeg;base64,{encoded_bytes} y pásalo en image.url.

¿Qué pasa si no defino aspect_ratio?

Si envías una imagen, la relación de aspecto coincide con la original. Sin imagen, el default es 16:9.

¿Cuánto cuesta un video de 10s a 720p?

Imagen: $0.002. Salida: 10 × $0.07 = $0.70. Total: $0.702.

¿Cuáles son los límites de rate?

60 solicitudes/minuto y 1/segundo en total (POST+GET).

¿Puedo extender videos más de 15s?

Sí, usando POST /v1/videos/extensions puedes encadenar múltiples clips, cada uno con polling asíncrono.