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 una imagen estática y convertirla en un videoclip. Usted envía (POST) la URL de su imagen, un mensaje (prompt) y configuraciones opcionales a https://api.x.ai/v1/videos/generations. La API devuelve un request_id de inmediato. Luego, consulta (poll) GET /v1/videos/{request_id} hasta que el status se convierte en "done". La duración oscila entre 1 y 15 segundos. El precio comienza en $0.05 por segundo para una salida de 480p.

Introducción

El 28 de enero de 2026, xAI lanzó el modelo grok-imagine-video para acceso público a través de su API. Durante ese primer mes, el modelo generó 1.200 millones de videos y ocupó el primer lugar en la clasificación de texto a video de Artificial Analysis. La conversión de imagen a video es una de sus capacidades principales: usted le entrega a la API una fotografía y un mensaje descriptivo (prompt), y esta anima la fotografía en un videoclip corto listo para descargar como MP4.

Ese flujo asíncrono, donde se envía una tarea y luego se consulta su finalización, introduce un desafío de prueba que muchos desarrolladores pasan por alto. Su integración no termina cuando la primera solicitud POST devuelve 200. Termina cuando ha confirmado que el ciclo de consulta maneja correctamente los estados "processing", "done" y "failed" bajo condiciones de red reales.

Los Escenarios de Prueba de Apidog resuelven esto directamente. Puede construir una secuencia encadenada: enviar una solicitud POST a /v1/videos/generations, extraer el request_id, repetir la solicitud de consulta hasta que status == "done", y luego afirmar que la URL del video está presente. Descargue Apidog gratis para seguir el tutorial de pruebas más adelante en esta guía.

button

¿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. Se encuentra bajo el modelo grok-imagine-video y acepta una imagen como fotograma inicial del video de salida. El modelo estudia el contenido de la imagen y el mensaje de texto (prompt), luego genera movimiento natural para animar la escena.

El endpoint de la API es:

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

La autenticación utiliza un token Bearer estándar:

Authorization: Bearer YOUR_XAI_API_KEY

Puede obtener su clave desde la consola de xAI. La misma superficie de API también es compatible con texto a video (omitir el parámetro image), extensiones de video y ediciones de video.

Cómo funciona el proceso de imagen a video

El parámetro image en el cuerpo de la solicitud designa el primer fotograma del video de salida. El modelo no reemplaza la imagen. Comienza a partir de ella. Cada píxel en el primer fotograma proviene de su imagen de origen. Luego, el modelo predice cómo esa escena avanzaría en el tiempo basándose en su mensaje (prompt).

Por ejemplo: usted proporciona una fotografía de un lago de montaña al amanecer. Su mensaje (prompt) dice "suaves ondas se extienden por el agua mientras la niebla matutina se dispersa". El primer fotograma del video de salida es su fotografía. Los fotogramas posteriores muestran el agua y la niebla animándose según el mensaje.

Esto es diferente del texto a video, donde el modelo genera el primer fotograma por sí mismo. La imagen a video le da un control exacto sobre la escena inicial.

Debe elegir imagen a video cuando: - Tenga fotos de productos, paisajes o retratos existentes que desee animar. - Sus activos de marca necesiten una identidad visual consistente en el primer fotograma. - Quiera que el movimiento se sienta arraigado en una escena real o específica.

Debe elegir texto a video cuando: - Esté explorando ideas visuales sin una imagen de referencia. - Quiera que el modelo decida la composición de la escena por completo. - La velocidad de iteración importe más que la precisión del primer fotograma.

Prerrequisitos

Antes de realizar su primera llamada, necesita:

1. Una cuenta xAI en console.x.ai.
2. Una clave API desde la consola de xAI. Mantenga esto en una variable de entorno, no codificado directamente.
3. Python 3.8+ o Node.js 18+ (los ejemplos en esta guía usan ambos).
4. Una URL de imagen accesible públicamente, o una imagen codificada en base64 como URI de datos.

Establezca su clave como una variable de entorno:

export XAI_API_KEY="your_key_here"

Instale el SDK de Python de xAI si desea el cliente de nivel superior:

pip install xai-sdk

Para llamadas HTTP directas, no se requieren paquetes adicionales más allá de requests (Python) o fetch (Node.js).

Realizando su 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"
  }'

La respuesta se devuelve inmediatamente con un request_id:

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

El video aún no está listo. La generación ocurre de forma asíncrona en la infraestructura de xAI. Necesita consultar (poll) el resultado.

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 su imagen es local o no es accesible públicamente, codifíquela como una URI de datos:

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 de video es asíncrona. La API devuelve un request_id mientras su video se renderiza en los servidores de xAI. Debe consultar (poll) el endpoint de estado:

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

El campo de estado pasa por estos valores:

Una respuesta completada se ve así:

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

Ciclo completo de consulta (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)

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

Mantenga el intervalo de consulta en 5 segundos o más. La API tiene un límite de tasa de 60 solicitudes por minuto (1 por segundo). Una consulta muy frecuente en múltiples trabajos simultáneamente puede agotar ese presupuesto rápidamente.

Usando el SDK de Python de xAI

La librería xai-sdk envuelve el patrón asíncrono por usted. client.video.generate() envía el trabajo y se bloquea hasta que el video está listo, manejando toda la consulta (polling) internamente:

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")

El SDK maneja el ciclo de consulta, las verificaciones de estado y la propagación de errores. Use este enfoque cuando desee un código de aplicación limpio sin tener que gestionar la consulta HTTP usted mismo.

Para un control granular sobre los intervalos de consulta, las estrategias de reintento o el registro, el enfoque de solicitudes directas le brinda más flexibilidad.

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

La API de video de Grok le da control directo sobre el formato de salida.

Duración

El parámetro duration acepta números enteros de 1 a 15 segundos. El valor predeterminado es 6.

"duration": 10

Los videos más largos cuestan más. Un clip de 10 segundos cuesta aproximadamente 10 veces uno de 1 segundo con la misma resolución.

Resolución

Hay dos opciones disponibles:

"resolution": "720p"

Relación de aspecto

El parámetro aspect_ratio controla las dimensiones del fotograma de salida:

Cuando proporciona una image, la relación de aspecto por defecto coincide con las dimensiones de la imagen de origen. Establézcala explícitamente para anular o recortar.

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

El parámetro reference_images es distinto del parámetro image. Comprender la diferencia es importante.

image: La fotografía de origen que se convierte en el primer fotograma del video. El modelo anima desde este punto de partida.

reference_images: Un array de hasta 7 imágenes que guían el estilo, contenido o contexto visual del video generado. Estas no son fotogramas en la salida. Influyen en cómo el modelo renderiza el movimiento y la apariencia.

Utilice reference_images cuando desee que el video de salida adopte características visuales de activos existentes, pero no como fotograma inicial:

{
  "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"
}

En este ejemplo, product-shot.jpg es el primer fotograma. Las imágenes de referencia guían la iluminación y el tratamiento estilístico.

Puede proporcionar imágenes de referencia sin una imagen de primer fotograma en absoluto. En ese caso, el modelo genera una salida de texto a video mientras obtiene guía de estilo de las referencias.

Extendiendo y editando videos

La API soporta dos operaciones adicionales más allá de la generación inicial.

Extendiendo un video

POST /v1/videos/extensions toma un video existente y genera segundos adicionales desde donde se quedó. Esto es útil para crear clips más largos a partir de múltiples pases de generación, manteniéndose dentro del límite de 15 segundos 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
  }'

La respuesta sigue el mismo patrón asíncrono: consulte (poll) GET /v1/videos/{request_id} para el clip extendido.

Editando un video

POST /v1/videos/edits aplica modificaciones guiadas por mensajes (prompt) a un video existente. Puede cambiar aspectos específicos del contenido o movimiento sin regenerar desde cero.

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"
  }'

Tanto las extensiones como las ediciones son asíncronas y utilizan el mismo patrón de consulta (polling).

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

La API de video de xAI cobra por dos componentes: el procesamiento de la imagen de entrada y la duración del video de salida.

Ejemplo: Video de 10 segundos a 720p

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

Ejemplo: Video de 6 segundos a 480p (configuración predeterminada)

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

El cargo por imagen de entrada se aplica cada vez que envía una solicitud de generación, incluso si reutiliza la misma URL de imagen. Planifique sus llamadas de generación en consecuencia si está iterando sobre la misma imagen base.

El texto a video (sin el parámetro image) omite el cargo de entrada de $0.002, pero por lo demás sigue el mismo precio por segundo.

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

El patrón asíncrono crea un desafío de prueba que las pruebas simples de una sola solicitud no pueden cubrir. Debe verificar que:

1. La solicitud de generación devuelve un request_id.
2. La solicitud de consulta (polling) maneja correctamente el estado "processing" mientras espera.
3. La respuesta final tiene status == "done" y una URL de video no vacía.

Los Escenarios de Prueba de Apidog encadenan estos pasos en un único flujo automatizado. Así es como se construye:

Paso 1: Crear un nuevo Escenario de Prueba

En Apidog, abra el módulo de Pruebas y haga clic en el botón + para crear un nuevo escenario. Nómbrelo "Grok image-to-video async flow."

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

Añada un paso de solicitud POST personalizado:

• 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

Después del paso POST, añada un procesador de Extraer Variable. Configúrelo:

• Nombre de la variable: video_request_id
• Fuente: Cuerpo de la respuesta
• Método de extracción: JSONPath
• Expresión JSONPath: $.request_id

Apidog almacena el valor extraído en {{video_request_id}} para usarlo en pasos posteriores.

Paso 4: Construir el ciclo de consulta (polling)

Añada un procesador de bucle For. Dentro del bucle, añada la solicitud de consulta:

• URL: https://api.x.ai/v1/videos/{{video_request_id}}
• Método: GET
• Cabecera: Authorization: Bearer {{xai_api_key}}

Añada un procesador de Extraer Variable dentro del bucle para capturar el estado actual:

• Nombre de la variable: video_status
• JSONPath: $.status

Añada un procesador de Espera (5000ms) después de la extracción del estado para evitar alcanzar el límite de tasa.

Establezca la condición de Ruptura si del bucle: {{video_status}} == "done".

Paso 5: Afirmar la URL del video

Después del bucle For, añada un paso GET final al mismo endpoint de consulta. Añada un procesador de Aserción:

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

Esta aserción confirma que la URL del video está presente antes de que su prueba se considere exitosa.

Para una mirada más profunda sobre cómo probar APIs asíncronas con Apidog, incluyendo patrones de consulta más complejos e integración CI/CD, consulte esa guía dedicada.

Ejecutando el escenario

Haga clic en Ejecutar en la vista del escenario de prueba. Apidog ejecuta el POST, extrae el request_id, repite la consulta hasta que status == "done", y luego evalúa sus aserciones. El informe de prueba muestra el estado y el tiempo de cada paso.

Puede integrar este escenario en su pipeline de CI/CD con la CLI de Apidog:

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

Errores comunes y soluciones

401 No autorizado

Su clave API no está presente o es inválida. Verifique el formato de la cabecera Authorization: Bearer YOUR_XAI_API_KEY. Confirme que la clave esté activa en la consola de xAI.

422 Entidad no procesable

El cuerpo de la solicitud está mal formado. Causas comunes: falta el campo model, el prompt está vacío o la image.url no es accesible. Pruebe la URL de la imagen en un navegador antes de usarla.

URL de imagen no accesible

Los servidores de xAI deben poder obtener la URL de la imagen en el momento de la generación. Las URLs privadas, las direcciones de localhost o las URLs detrás de autenticación fallarán. Use una CDN pública o una URI de datos base64 en su lugar.

El estado permanece en "processing" indefinidamente

Una generación puede tardar entre 30 segundos y varios minutos, dependiendo de la resolución y la duración. Si el estado permanece en "processing" más allá de 10 minutos, el trabajo podría haberse atascado. Envíe una nueva solicitud. La API de xAI actualmente no expone una señal de tiempo de espera separada de "failed".

Errores de límite de tasa (429)

La API permite 60 solicitudes por minuto y 1 por segundo. Si está consultando múltiples trabajos simultáneamente, escalone sus solicitudes. Añada un time.sleep(1) entre las llamadas de consulta como mínimo.

Carga Base64 rechazada

Asegúrese de que su URI de datos incluya el prefijo de tipo MIME correcto. Use data:image/jpeg;base64, para archivos JPEG y data:image/png;base64, para archivos PNG.

Desajuste de la relación de aspecto

Cuando establece una aspect_ratio explícita que difiere significativamente de las proporciones de su imagen de origen, el modelo puede recortar o aplicar bandas negras. Haga coincidir la relación de aspecto con su imagen de origen para obtener los mejores resultados.

Conclusión

La API de imagen a video de Grok le ofrece un camino directo desde una fotografía estática a un clip animado corto. Usted envía la imagen y el mensaje (prompt), recibe un request_id, consulta (poll) hasta que finaliza, y descarga el MP4. El modelo grok-imagine-video se clasificó en la cima de la tabla de clasificación de Artificial Analysis en enero de 2026. Más de mil millones de videos fueron generados en ese único mes. Esa escala refleja la capacidad del modelo subyacente.

El patrón de consulta (polling) asíncrona es donde la mayoría de las integraciones fallan. Una prueba adecuada en los Escenarios de Prueba de Apidog cubre el paso de Extracción de Variable, el ciclo de consulta con condición de ruptura y una aserción final de URL. Esa combinación detecta problemas antes de que lleguen a producción.

button

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

Preguntas Frecuentes

¿Qué nombre de modelo utilizo para la API de imagen a video de Grok?

El nombre del modelo es grok-imagine-video. Páselo como el campo model en el cuerpo de su solicitud POST.

¿Cuál es la diferencia entre los parámetros image y reference_images?

El parámetro image establece el primer fotograma del video de salida. El modelo anima hacia adelante desde esa imagen inicial. El array reference_images proporciona guía de estilo y contenido sin ser utilizado como fotograma. Puede combinar ambos en la misma solicitud.

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

El tiempo de generación varía según la duración y la resolución. Un video de 480p de 6 segundos suele tardar de 1 a 3 minutos. Un video de 720p de 15 segundos puede tardar de 4 a 8 minutos. Consulte (poll) cada 5 segundos para verificar el estado sin agotar su límite de tasa.

¿Puedo usar un archivo local como imagen de origen?

Sí. Codifique su archivo local como una URI de datos base64: data:image/jpeg;base64,{encoded_bytes}. Pase esa cadena como el valor url dentro del objeto image.

¿Qué sucede si no especifico la aspect_ratio?

Cuando proporciona un parámetro image, la relación de aspecto por defecto coincide con las proporciones nativas de la imagen de origen. Al generar texto a video sin una imagen, el valor predeterminado es 16:9.

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

La imagen de entrada cuesta $0.002. La salida cuesta 10 × $0.07 = $0.70. Total: aproximadamente $0.702 por video.

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

La API permite 60 solicitudes por minuto y 1 solicitud por segundo. Esto cubre tanto las solicitudes POST de generación como las solicitudes GET de consulta combinadas.

¿Puedo extender un video más allá de 15 segundos?

Sí, utilizando el endpoint POST /v1/videos/extensions. Usted genera un clip inicial de hasta 15 segundos, luego lo extiende con pases de generación adicionales. Cada extensión también sigue el patrón de consulta (polling) asíncrona.