Cómo usar la API de Grok Imagine para texto a video: curl, Python y una solicitud ejecutable

Grok Imagine es el modelo de generación de video de xAI, y HiAPI expone su variante de texto a video a través del mismo endpoint asíncrono unificado que el resto de los modelos de generación: POST /v1/tasks. Envías un prompt (más duración, modo, relación de aspecto y resolución opcionales), recibes de inmediato un taskId y obtienes una URL .mp4 cuando la tarea finaliza.

Esta guía es el camino más corto hacia una solicitud ejecutable: el esquema de entrada exacto (verificado contra la API en producción, incluido el error 400 que recibirás si adivinas mal el nombre de un campo), el flujo curl que puedes copiar y pegar, un pequeño cliente de Python con sondeo y el patrón de callback que usarás en producción.

Qué vas a construir y qué necesitas

Objetivo: convertir un prompt de texto en un clip de 6–30 segundos completamente por HTTP, a través de grok-imagine/text-to-video.

Solo necesitas una cosa: una clave de API de HiAPI. Créala en el panel de HiAPI: una sola clave sirve para todos los modelos, así que si ya has llamado a modelos de imagen en HiAPI, la misma clave funciona aquí. Las solicitudes se autentican con la cabecera bearer estándar:

Authorization: Bearer sk-<your-key>

El esquema de entrada (antes de escribir código)

La API de tareas valida input de forma estricta por modelo: los campos desconocidos se rechazan con un 400 en lugar de ignorarse en silencio. Este es el esquema completo de grok-imagine/text-to-video:

Campo	Tipo	Obligatorio	Valores	Predeterminado
prompt	string	Sí	Máximo 5000 caracteres; funciona mejor en inglés	—
duration	integer	No	6–30 (segundos)	6
mode	enum	No	fun, normal	normal
aspect_ratio	enum	No	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	No	480p, 720p	480p

Hay tres cosas que conviene saber de antemano:

• mode es el interruptor del «modo de movimiento». normal es equilibrado; fun produce un movimiento más creativo y exagerado. Si has visto los modos de Grok Imagine descritos con otros nombres en otro sitio, el parámetro de la API es mode: enviar algo como motion_mode te devolverá 400 additional properties 'motion_mode' not allowed.
• duration afecta al coste de forma lineal. Grok Imagine factura por segundos de salida, así que un clip de 30 segundos cuesta 5 veces más que uno de 6 segundos. Consulta la tarifa actual por segundo en la página de precios de HiAPI.
• La relación de aspecto predeterminada es 2:3 (vertical). Si quieres pantalla ancha, pasa 16:9 explícitamente: esto pilla desprevenidos a quienes migran desde modelos cuyo valor predeterminado es horizontal.

Los valores fuera de rango fallan rápido con un mensaje descriptivo; por ejemplo, duration: 31 devuelve:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Ejemplo mínimo ejecutable: curl

Dos llamadas: crear la tarea y luego sondearla.

1. Crear la tarea:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Fíjate en que el id del modelo es la cadena literal grok-imagine/text-to-video: sin prefijo de proveedor ni sufijo de versión.

2. Sondear hasta el estado final:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

La URL .mp4 es temporal: expireAt es una marca de tiempo Unix de aproximadamente una semana después. Descarga los bytes y persístelos por tu cuenta justo después de que la tarea tenga éxito; no enlaces en caliente las URL de temp.hiapi.ai desde ninguna parte visible para el usuario. (Si alguna vez te has encontrado con enlaces de salida caducados, la causa está aquí: consulta la URL de salida de hiapi ha caducado: descárgala antes de que expire).

Python: un pequeño cliente de sondeo

Un script reutilizable para el mismo flujo: crear, sondear con fecha límite y descargar:

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

Un clip de 6 segundos suele terminar muy por debajo del límite de 15 minutos indicado arriba; las duraciones más largas tardan proporcionalmente más, así que mantén ese tiempo de espera holgado para tareas de 30 segundos.

Consideraciones para producción

Usa callbacks en lugar de sondeo. Para cualquier escenario más allá de un script, pasa un objeto callback de nivel superior al crear la tarea y HiAPI enviará por POST el estado final de la tarea a tu endpoint, sin necesidad de mantener un bucle de sondeo:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when solo acepta "final" (recibirás un único POST cuando la tarea alcance success o fail, no progreso incremental). Regla general: el sondeo va bien para CLI, trabajos por lotes y cualquier escenario de corta duración; los callbacks van bien para backends web, donde de otro modo ocuparías la capacidad de tus workers con renderizaciones de varios minutos. Si tu endpoint de callback parece no recibir nada, investiga por qué no se dispara el callback de tu tarea de hiapi.

Idempotencia. La creación de tareas no es idempotente: reintentar una solicitud de creación que agotó el tiempo de espera puede generar dos tareas facturadas. Registra el taskId en el momento en que lo obtengas y, ante un fallo ambiguo (tiempo de espera de red durante la creación), revisa tu historial de tareas antes de reenviar. Como duration se factura por segundos, una tarea duplicada de 30 segundos es el tipo de duplicado caro.

Manejo de errores. Los dos tipos de error que verás en la práctica:

• Errores 400 de esquema (error_code: "INVALID_REQUEST"): nombre de campo incorrecto, duración fuera de rango, valor de enum no válido. Son deterministas; corrige la solicitud, no reintentes.
• Fallos de autenticación: una clave no válida o una clave sin acceso a este modelo devuelve 401 con "code": "permission_denied" y el mensaje "This API key cannot use the selected model." Revisa la clave en el panel y confirma que el modelo está habilitado para ella.
• Fallos a nivel de tarea: la creación tiene éxito, pero la tarea pasa después a un estado final con status: "fail" y un objeto error (política de contenido, capacidad del proveedor ascendente). Merece la pena reintentar una vez con retroceso exponencial. Si una tarea parece quedarse en handling, consulta diagnosticar trabajos de /v1/tasks colgados o agotados por tiempo de espera.

Siguientes pasos

• Página del modelo Grok Imagine de texto a video: playground y precios actuales
• Referencia de entrada del modelo: esquema canónico de este modelo
• Crear tarea y Obtener detalles de la tarea: el sobre completo de la API asíncrona
• Inicio rápido: completa tu primera llamada a HiAPI de extremo a extremo, y Autenticación para el manejo de claves

Preguntas frecuentes

¿Qué es la API de Grok Imagine y cómo accedo a ella? Grok Imagine es el modelo de generación de video de xAI. A través de HiAPI, lo llamas como grok-imagine/text-to-video en el endpoint unificado POST /v1/tasks con una única clave de HiAPI: no necesitas una cuenta de xAI ni un SDK aparte.

¿Cuánto puede durar un video de Grok Imagine? duration acepta enteros de 6 a 30 segundos (predeterminado 6). Los valores fuera de ese rango se rechazan con un 400 al crear la tarea, y la facturación se calcula por segundos de salida.

¿Cuál es la diferencia entre los modos fun y normal? normal (predeterminado) ofrece un movimiento equilibrado y realista; fun tira más hacia lo creativo y exagerado. Es el único interruptor de estilo de movimiento que expone la API: se elige por solicitud, no por cuenta.

¿grok-imagine/text-to-video admite 1080p? Actualmente no: resolution acepta 480p (predeterminado) o 720p. Si necesitas una resolución de salida mayor, escala en una etapa posterior o compara otros modelos de video en la página de modelos.

¿Puedo usar Grok Imagine para animar una imagen existente? Con este modelo no: solo admite texto. En el mismo endpoint de tareas hay un modelo aparte, grok-imagine/image-to-video, que acepta una imagen de entrada; el ciclo de vida asíncrono (crear → sondear/callback → descargar) es idéntico.

¿La API de Grok Imagine tiene nivel gratuito? La generación se factura contra tu saldo de HiAPI según los segundos de video: no hay un endpoint gratuito sin clave. Consulta las tarifas actuales en la página de precios; sobre cómo es realmente lo «gratuito» en este terreno, esta comparativa de API de texto a video gratuitas cubre las distintas opciones.