Práctica con la API de Grok-Video-3: todo lo que necesitas saber sobre el motor de vídeo de xAI
Modelos objetivo:
grok-video-1.5,grok-video-1.0
Endpoint de inferencia:https://api.toapis.com/v1/videos/generations
Relacionado: Acceso compatible con OpenAI · API del canal oficial de Grok Imagine · Guía de vídeo de Hailuo 2.3 · Referencia de Grok Video 1.5
1. Resumen y panorama del rendimiento
- Primero el catálogo: las solicitudes para una integración práctica de Grok Video 3 tienen que partir igualmente de los ID que ToAPIs publica realmente. La instantánea pública del catálogo de producción fechada el 2026-11-10 lista
grok-video-1.0ygrok-video-1.5en el endpointopenai-video. Una comprobación del 2026-11-17 de las URL de documentación y de guía de modelo degrok-video-3devolvió HTTP 404. - Contrato: envía de forma asíncrona a
POST /v1/videos/generationsy luego consultaGET /v1/videos/generations/{id}hastacompletedofailed. Los ejemplos oficiales usanhttps://toapis.com(yhttps://toapis.cnpara China continental). Otras guías de esta serie usanhttps://api.toapis.com. Elige un origen y mantenlo coherente. - Modos:
grok-video-1.5documentatext_to_video,first_frame_image_to_videoyreference_images_to_video. Ajustavideo_generation_modede forma explícita para que una única imagen de referencia no se trate como un trabajo heredado de primer fotograma. - Medios: envía solo URL públicas
http://ohttps://. Sube los archivos locales conPOST /v1/uploads/imagesy usa eldata.urldevuelto. No envíes base64. - Afirmaciones sin verificar que hay que descartar: los borradores de planificación que citan un ID
grok-video-3, un SLA del 99,95 %, una tarifa fija de$0.030–$0.038por segundo o una fecha futura de lanzamiento de audio no son documentación actual de ToAPIs. Confirma las tarifas vigentes y el soporte del canal en tu cuenta.
2. ID actuales de Grok Video y modos de generación
Usa el nombre público del modelo en el campo model. No lo sustituyas por un nombre nativo del proveedor, un slug de URL ni una cadena grok-video-3 no publicada.
| ID de catálogo | Trabajos documentados | Duración (docs) | Resolución | Entradas de imagen |
|---|---|---|---|---|
grok-video-1.5 | Texto, primer fotograma o 1 a 7 imágenes de referencia, seleccionados con video_generation_mode | Entero de 1–15 segundos | 480p o 720p en modo de referencia; texto y primer fotograma pueden usar 1080p cuando el canal lo admite | Primer fotograma: exactamente un image o input_reference. Modo de referencia: 1 a 7 reference_images |
grok-video-1.0 | Texto a vídeo e imagen a vídeo | Referencia de generación: 1–15 segundos (predeterminado 8). Guía de modelo / playground: un tope de 6 segundos en la variante disponible actualmente | 480p, 720p | image opcional más reference_images; hasta 8 imágenes en total |
Para grok-video-1.5, las integraciones nuevas deberían fijar el modo explícitamente:
video_generation_mode | Entrada obligatoria | Qué debe omitir |
|---|---|---|
text_to_video | prompt no vacío | Cualquier campo de imagen |
first_frame_image_to_video | Exactamente un primer fotograma en image o input_reference | Valores en conflicto en ambos alias; tampoco envíes una lista de referencias salvo que la referencia de tu cuenta indique lo contrario |
reference_images_to_video | prompt más 1 a 7 reference_images (cadenas u objetos {"url":"..."}) | Apoyarte en una única entrada de reference_images sin este modo: la entrada heredada de una sola imagen sigue siendo comportamiento de primer fotograma |
Una cotización de precio correcta no garantiza que el canal de generación esté abierto. Los modos solo están disponibles cuando se habilitan en un canal compatible; las combinaciones no admitidas pueden rechazarse antes de crear la tarea.
Los valores de relación de aspecto habituales en las referencias de Grok Video son 16:9, 9:16, 3:2, 2:3 y 1:1. La disponibilidad sigue dependiendo del canal, así que envía un valor que hayas confirmado para ese ID.

Figura 1: envía un prompt (y URL públicas de imagen opcionales) a POST /v1/videos/generations, consulta el mismo id de tarea y lee result.data[0].url solo cuando el estado sea completed.
Si necesitas funciones del canal oficial de Grok Imagine, como la extensión de vídeo, esa es otra familia de ID: consulta la guía del canal oficial de Imagine. Para un segundo contrato de vídeo con una matriz de duración distinta, consulta la guía de Hailuo 2.3.
3. Implementación en producción: cURL y Python
Los ejemplos internacionales de esta serie usan https://api.toapis.com. La documentación oficial indica a los usuarios de China continental que usen https://toapis.cn. Mantén un solo origen por entorno. Las rutas, los ID de modelo y la cabecera Bearer no cambian.
Paso 1: envío con cURL para grok-video-1.5
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Un trabajo con primer fotograma usa la misma ruta con "video_generation_mode": "first_frame_image_to_video" y una URL en image. Un trabajo con imágenes de referencia fija "video_generation_mode": "reference_images_to_video" y una lista reference_images, y mantiene resolution en 480p o 720p.
Paso 2: ayuda y sondeo en Python
El fragmento sigue la ruta de estado de tarea documentada y los estados queued / in_progress / completed / failed. Confirma id, result.data[0].url y el formato de respuesta con la referencia de la API de tu cuenta antes de publicar.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Guarda la versión de la plantilla de prompt junto al registro de la tarea para poder distinguir un cambio de modelo o de modo de un cambio de redacción. Descarga el archivo antes de expires_at; la referencia de estado documenta una ventana de retención de 30 días.
4. Gestión de errores y matriz de estados
Las categorías de abajo son puntos de partida para el diagnóstico, no una garantía de los códigos de error exactos de ToAPIs. Una consulta HTTP correcta sigue exigiendo leer el status de la tarea. Consulta la referencia de errores para distinguir errores de solicitud de motivos de status: failed como content_policy_rejected, insufficient_user_balance o generation_timeout.
| Estado HTTP o de tarea | Categoría habitual | Acción recomendada |
|---|---|---|
400 | Campo inválido, desajuste entre modo y medios o combinación no admitida | Revisa el ID exacto del catálogo, que video_generation_mode coincida con los campos de imagen, que el modo de referencia se mantenga en 480p o 720p y que los valores de imagen sean URL públicas |
401 | Clave de API ausente o inválida | Rota la clave en el panel de ToAPIs y confirma la cabecera Authorization: Bearer |
429 | Límite de frecuencia o de concurrencia | Respeta Retry-After cuando esté presente; retrocede con fluctuación aleatoria; reintenta solo cuando sea seguro |
5xx o tiempo de espera agotado del cliente | Problema temporal de la pasarela o del upstream | Consulta el id de tarea existente antes de reenviar |
status: queued o in_progress | No es un error | Espera y consulta de nuevo; no crees un segundo trabajo |
status: failed | La generación no tuvo éxito | Lee error.code y error.message (y error.reason cuando esté presente). No repitas un payload rechazado por política sin cambios |
5. Precios y retorno de FinOps
- No reutilices precios unitarios de borradores de planificación. La referencia de la API de
grok-video-1.5indica que el precio sigue la configuración actual de cuenta y SKU y que la página no garantiza un precio fijo por segundo. Las filas de referencia oficiales del proveedor en la página de precios de ToAPIs son solo informativas y pueden no coincidir con lo que se factura a tu cuenta. - Una cotización no es una garantía de canal. La referencia de 1.5 señala que una cotización de precio correcta no significa que haya un canal de generación disponible.
- Controla el gasto en la capa de prompt: haz borradores en
720py una duración intermedia como 8 segundos, mantén una plantilla versionada, cambia una variable cada vez y no reenvíes tras un tiempo de espera agotado del cliente hasta comprobar el estado de la tarea. - Los contratos oficiales de los proveedores suelen añadir compromisos anuales, cuotas por usuario y mínimos de prepago. La facturación de ToAPIs suele ser pago por uso: confirma las condiciones activas de tu cuenta.
6. Preguntas frecuentes
Consulta el bloque de preguntas frecuentes del frontmatter. En resumen: grok-video-3 no es un ID público de catálogo actual; empieza por grok-video-1.5 o grok-video-1.0; trata el tope de duración de 1.0 como una comprobación específica del canal; el audio sincronizado no está documentado; consulta siempre la ruta de estado de generaciones y guarda el id de la tarea.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Confirma que
grok-video-1.5ogrok-video-1.0aparece para tu clave medianteGET /v1/models?type=video; no envíesgrok-video-3salvo que aparezca después en esa lista y en la referencia de la API. - Haz una prueba rápida del fragmento de cURL con
video_generation_mode: "text_to_video",duration: 8yresolution: "720p". - Consulta
GET /v1/videos/generations/{id}con un plazo acotado y descarga el resultado antes deexpires_at. - Siguiente paso: la guía de acceso compatible con OpenAI si estás apuntando un cliente existente a ToAPIs, la guía del modelo Grok Video 1.5 para el estado del catálogo en vivo, y la guía del modelo Grok Video 1.0 antes de apoyarte en una duración superior a 6 segundos en ese ID.







