Grok Imagine Video API: texto a vídeo con Python

La API de Grok Imagine Video es asíncrona: envías un prompt para crear un trabajo, consultas el ID hasta que termina y descargas el MP4. El modelo actual es grok-imagine-video-1.5. El 24 de octubre de 2026, nuestro clip de 6 segundos en 720p estuvo listo 46 segundos después de enviar la petición, y traía pista de audio.

Abajo tienes el script que funciona tal cual, los parámetros que deciden el resultado, lo que cuesta un clip y lo que tarda, y los errores con los que te vas a encontrar.

Respuesta corta

• Modelo: grok-imagine-video-1.5. xAI dice que 1.5 salió de la vista previa y pasó a disponibilidad general el 16 de junio de 2026 (xAI).
• Ajustes: duration de 4 a 15 segundos, resolution "720p" y un ratio como "16:9".
• Coste: 0,14 USD por segundo en 720p según la lista de xAI, así que 0,84 USD por un clip de 6 segundos (página de modelos de xAI, revisada el 24 de octubre de 2026).
• Tiempo: nuestro trabajo de 6 segundos en 720p tardó 46 segundos. Consulta el mismo ID de tarea y descarga el archivo dentro de una hora.

¿Cómo funciona la API de Grok Imagine Video?

Es un trabajo de tres pasos: crear, consultar y descargar (guía de generación de vídeo de xAI, revisada el 24 de octubre de 2026).

En la API propia de xAI envías una petición POST a https://api.x.ai/v1/videos/generations con el ID del modelo y el prompt, y recibes un request_id. Después consultas https://api.x.ai/v1/videos/{request_id} con GET hasta que el trabajo esté done, y lees video.url (la misma guía).

xAI recomienda grok-imagine-video-1.5-lite para vídeos sencillos y grok-imagine-video-1.5 cuando necesitas referencias, voces, fotogramas fijados o 1080p nativo (resumen de vídeo, revisado el 24 de octubre de 2026). Para imágenes fijas, la guía de la API de imágenes de Grok Imagine cubre los tres modelos de imagen de xAI; para comparar Grok con otras API de vídeo, lee nuestra comparativa de modelos de vídeo.

OmniaKey vende acceso API a Grok Imagine Video 1.5, así que ejecutamos el ejemplo a través de él. Las llamadas son POST https://api.omniakey.com/v1/media/tasks con una cabecera Idempotency-Key, que responde 202 con un id, y GET /v1/media/tasks/{id} para el estado (resumen de medios de OmniaKey, revisado el 24 de octubre de 2026). El mismo flujo de crear, consultar y descargar sirve para los otros modelos de vídeo de la documentación de la API de vídeo: Kling 3.0, Seedance, Wan 3.0, MiniMax H3 y HappyHorse. Todos los precios de abajo son los de xAI.

Los nombres de campo de xAI vienen de su referencia de la API de vídeos y los de OmniaKey de su documentación de la API de vídeo, ambos revisados el 24 de octubre de 2026.

¿Qué parámetros puedes ajustar?

El prompt y tres ajustes deciden lo que obtienes.

• duration es obligatorio en OmniaKey y decide el precio (documentación de vídeo de OmniaKey). El mínimo de OmniaKey para este modelo son 4 segundos y el máximo de xAI son 15 (guía de generación de vídeo), así que quédate entre 4 y 15.
• resolution: envía "720p" en minúsculas. OmniaKey sirve el vídeo de Grok hasta 720p (resumen de medios de OmniaKey). La API propia de xAI añade 480p, su valor por defecto, y 1080p nativo (guía de generación).
• ratio acepta nueve valores: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 y 5:2, con 16:9 por defecto (guía de generación de vídeo). Nosotros usamos 16:9.
• n tiene que ser 1 (documentación de vídeo de OmniaKey).
• El prompt: describe el plano, la luz y el movimiento de cámara, y añade una línea Sound:. Todo lo que nombres ahí puede aparecer en pantalla: nuestra línea de sonido mencionaba una cuchara, y en la imagen salieron una cuchara y una mano.

¿Cómo conviertes un prompt de texto en vídeo con Python?

Instala requests, pon la clave en OMNIAKEY_API_KEY y ejecuta el script.

pip install requests
export OMNIAKEY_API_KEY="your-key"

Este es el script que ejecutamos, sin cambios:

import os
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

PROMPT = (
    "Close-up of a white ceramic coffee cup on a wooden café table by a window, "
    "morning sunlight, steam curling up from the coffee, the camera slowly pushes in, "
    "shallow depth of field. Sound: quiet café chatter and a spoon clinking on a saucer."
)

# 1. Crea el trabajo. Reutiliza la misma Idempotency-Key solo al reintentar esta petición exacta.
job = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "grok-imagine-video-1.5",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": PROMPT},
        "parameters": {"duration": 6, "resolution": "720p", "ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
task = job.json()
print("task:", task["id"], task["status"])

# 2. Consulta el trabajo hasta que termine. Un trabajo lento no ha fallado: sigue con el mismo id.
while True:
    task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] not in ("queued", "processing"):
        break
    time.sleep(5)

if task["status"] != "succeeded":
    raise SystemExit(f"job ended {task['status']}: {task.get('error')}")

# 3. Descarga el clip ahora: la URL firmada caduca en cerca de una hora.
asset = task["assets"][0]
with open("coffee.mp4", "wb") as f:
    f.write(requests.get(asset["url"], timeout=120).content)
print("saved coffee.mp4", asset["mime_type"], asset["byte_size"], "bytes")

Su última línea de salida el 24 de octubre de 2026:

saved coffee.mp4 video/mp4 2659230 bytes

La primera línea del script imprime el ID del trabajo y su estado. Guarda ese ID: es como vuelves a encontrar el trabajo si el script se para.

Un trabajo de 6 segundos en 720p volvió así:

El clip sigue el prompt: una taza blanca de cerámica con café negro sobre un platillo blanco, en una mesa de madera junto a una ventana, con vapor subiendo y la cafetería desenfocada detrás. La cámara avanza con paso constante y la taza pasa de ocupar cerca de un tercio del ancho del encuadre a cerca de la mitad. A los 4,5 segundos entra una cuchara desde la derecha. El audio es una pista tranquila con un pico marcado a los 4,8 segundos, justo cuando la cuchara toca el platillo.

¿Cuánto cuesta un clip y cuánto tarda?

xAI cobra el vídeo por segundo, y la tarifa depende del modelo y la resolución. Su página de modelos (revisada el 24 de octubre de 2026) desglosa el precio por resolución, y los 0,080 USD por segundo planos de su página de precios son la tarifa de 480p.

Con esos precios de lista:

• 6 segundos en 1.5 a 720p: 6 × 0,14 = 0,84 USD.
• 8 segundos, la longitud por defecto, en 1.5 a 480p: 8 × 0,08 = 0,64 USD.
• 15 segundos en 1.5 a 1080p: 15 × 0,25 = 3,75 USD.
• 6 segundos en 1.5 Lite a 720p: 6 × 0,03 = 0,18 USD.

xAI solo publica tarifas de vídeo por segundo (página de precios, revisada el 24 de octubre de 2026).

En OmniaKey el cargo es la duración que pides multiplicada por la tarifa por segundo, se descuenta del saldo al crear el trabajo y se devuelve solo si el trabajo falla (documentación de vídeo de OmniaKey, revisada el 24 de octubre de 2026). Nuestra petición de 6 segundos devolvió un archivo de 6,04 segundos y se cobró como 6 segundos. Las tarifas actuales están en la página de Grok Imagine Video 1.5.

Nuestro trabajo tardó 46 segundos desde la petición hasta succeeded. xAI dice que la generación "suele tardar varios minutos como máximo", y su SDK espera hasta 10 minutos (guía de generación). Consulta cada pocos segundos. Si añades un límite de tiempo al bucle, dale margen, y cuando se cumpla, vuelve a buscar el trabajo por su ID en lugar de enviar otra petición.

El enlace firmado vive cerca de una hora, y el nuestro caducó exactamente una hora después de que terminara el trabajo. El registro de la tarea se guarda 24 horas, así que puedes consultar de nuevo para obtener un enlace fresco (resumen de medios de OmniaKey, revisado el 24 de octubre de 2026).

¿Con qué errores te vas a encontrar?

La mayoría de los errores vuelven enseguida, antes de crear un trabajo, así que no cuestan nada. Un trabajo que falla más tarde termina como failed y se devuelve el dinero. La documentación de medios de OmniaKey (revisada el 24 de octubre de 2026) incluye estos, entre otros:

Provocamos los dos primeros a propósito el 24 de octubre de 2026. Omitir la cabecera devolvió HTTP 400:

{"error":{"code":"missing_idempotency_key","message":"Idempotency-Key is required and must be at most 255 characters"}}

Reutilizar la clave del trabajo con un prompt distinto devolvió HTTP 409:

{"error":{"code":"idempotency_key_reused","message":"Idempotency-Key was already used with a different request"}}

• Trata un trabajo lento como si siguiera en marcha. Sigue consultando el mismo ID de tarea; enviar la petición otra vez con una Idempotency-Key nueva arranca un segundo trabajo y lo cobra.
• Una petición repetida responde 200 con la tarea original y sin lista assets, y por eso el script busca la tarea antes de leer assets.

Preguntas frecuentes

¿La API de Grok Imagine Video es gratis?

No. xAI solo publica tarifas por segundo, y la más barata es 1.5 Lite a 0,02 USD por segundo en 480p (página de modelos, revisada el 24 de octubre de 2026).

¿Cuánto puede durar un vídeo de Grok Imagine?

De 1 a 15 segundos en la API de xAI, y 8 segundos por defecto (guía de generación de vídeo). A través de OmniaKey, usa de 4 a 15 segundos: el mínimo de OmniaKey para este modelo es 4 (documentación de vídeo de OmniaKey, revisada el 24 de octubre de 2026) y el máximo de xAI es 15.

¿Grok Imagine Video genera sonido?

Sí, una pista de audio por defecto, con efectos de sonido, ambiente y diálogo generados junto a la imagen (guía de generación de vídeo; anuncio de xAI). El nuestro tenía una pista AAC estéreo. La API de xAI acepta generate_audio: false para un clip mudo; para quitar la pista de un archivo descargado, ejecuta:

ffmpeg -i coffee.mp4 -an -c:v copy coffee-silent.mp4

¿Grok Imagine puede convertir una imagen en vídeo?

Sí, en la API de xAI: pasa la imagen como image (una URL pública, un data URI en base64 o un file_id de la Files API; JPEG, PNG o WebP), se convierte en el primer fotograma, el prompt es opcional y el clip conserva la relación de aspecto de la imagen (guía de imagen a vídeo; referencia de la API de vídeos). Añadiremos aquí un ejemplo de imagen a vídeo con OmniaKey cuando lo hayamos verificado de principio a fin.

¿Cuál es la diferencia entre Grok Imagine Video 1.5 y 1.5 Lite?

Lite es el más barato por segundo, hace texto a vídeo e imagen a vídeo con voz sincronizada con los labios, llega a 1080p escalando 720p y no tiene imágenes de referencia, referencias de voz ni fotogramas clave (resumen de vídeo; página del modelo Lite). Los ejemplos de aquí usan 1.5, que puedes llamar en OmniaKey como Grok Imagine Video 1.5.

¿grok-imagine-video-1.5-preview sigue siendo un ID de modelo válido?

xAI todavía lo lista como alias, pero 1.5 salió de la vista previa y pasó a disponibilidad general el 16 de junio de 2026 (página del modelo; anuncio de xAI). Usa grok-imagine-video-1.5.