Cómo acceder a la API de Grok Video 3 mediante endpoints compatibles con OpenAI
Modelos objetivo:
grok-video-1.5,grok-video-1.0
Endpoint de inferencia:https://api.toapis.com/v1/videos/generations
Relacionado: Guía práctica de Grok Video · API del canal oficial de Grok Imagine · Configuración compatible con OpenAI en Chatbox · Listar modelos
1. Resumen y panorama del rendimiento
- Qué significa «compatible con OpenAI» aquí: ToAPIs documenta un único origen
/v1, autenticación Bearer y una lista de modelos y una API de finalizaciones de chat al estilo OpenAI. Los ID públicos de Grok Video están registrados en la familia de endpointsopenai-videodel catálogo. Eso no significa que funcione un IDgrok-video-3no publicado, y por sí solo no documenta un método del SDK de OpenAI Videos. - ID: usa
grok-video-1.5ogrok-video-1.0después de que aparezcan para tu clave enGET /v1/models?type=video. La instantánea pública del catálogo fechada el 2026-11-10 no listagrok-video-3. - Ruta de vídeo: crea con
POST /v1/videos/generations. Consulta conGET /v1/videos/generations/{id}. Los ejemplos oficiales usanhttps://toapis.com(yhttps://toapis.cnpara China continental). Esta serie también usahttps://api.toapis.com. - Autenticación compartida: una clave API en
Authorization: Bearer. No existe un documento público separado de ámbitos OAuth para estas llamadas de vídeo. - Elección de cliente: usa el SDK de OpenAI contra
base_url="https://api.toapis.com/v1"para trabajo de tipo chat y para una configuración familiar de clave y origen. Para Grok Video, esta guía usa el cuerpo JSON REST documentado, para quevideo_generation_modey los campos de URL de imagen queden explícitos.
2. Origen compatible, lista de modelos y rutas de vídeo
Mantén juntos el origen, el prefijo /v1 y la clave. Mezclar una clave de ToAPIs con https://api.openai.com/v1, o un origen de ToAPIs con una ruta nativa de Grok del proveedor, es una configuración distinta y no documentada.
| Paso | Ruta documentada | Notas |
|---|---|---|
| Listar modelos | GET /v1/models?type=video | GET /v1/models predeterminado devuelve solo modelos de texto. Usa type=video o type=all |
| Subir una imagen local | POST /v1/uploads/images (file multipart) | Lee data.url. No envíes base64 en la llamada de generación |
| Crear un trabajo de Grok Video | POST /v1/videos/generations | El cuerpo incluye model, prompt y los campos de modo y medios de 1.5 |
| Consultar estado | GET /v1/videos/generations/{id} | Los estados finales son completed y failed |
| Chat (no vídeo) | POST /v1/chat/completions | Comparte solo el origen y la clave |
En grok-video-1.5, ajusta video_generation_mode a text_to_video, first_frame_image_to_video o reference_images_to_video para que el JSON coincida con los medios que envías. El contrato por campo está en la guía práctica de Grok Video y en la referencia de la API de Grok Video 1.5.

Figura 1: apunta el cliente a un origen /v1 de ToAPIs, descubre grok-video-1.5 o grok-video-1.0 con la lista de modelos y luego envía y consulta en /v1/videos/generations, no en chat/completions.
Si estás configurando un cliente de escritorio en lugar de código de aplicación, la guía de configuración de Chatbox cubre el patrón del campo de host para chat. No esperes que esa misma ruta de chat devuelva un archivo de vídeo.
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.
Paso 1: descubre el ID y luego envía con cURL
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
Revisa la lista de modelos para ver la cadena id exacta antes de fijarla por código. Si grok-video-3 no aparece, no lo envíes.
Paso 2: Python, origen compartido y llamadas de vídeo REST
El SDK de OpenAI se muestra solo para la base_url y la clave API compartidas. La creación y la consulta de vídeo se mantienen en las rutas de generaciones documentadas, para que los campos del cuerpo de 1.5 no se pierdan en un mapeo de cliente no oficial.
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
Si la llamada de lista devuelve un formato inesperado, registra el JSON sin procesar y ajusta el lector a la página de Listar modelos de tu cuenta. No inventes un respaldo que envíe grok-video-3 cuando el ID falta.
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.
| Estado HTTP o de tarea | Categoría habitual | Acción recomendada |
|---|---|---|
400 | ID de modelo desconocido, desajuste entre modo y medios, o un cuerpo de vídeo enviado a una ruta de chat | Confirma el ID en GET /v1/models?type=video, que enviaste a /v1/videos/generations y que los trabajos de 1.5 definen un video_generation_mode coherente |
401 | Clave de API ausente o inválida | Usa una clave de ToAPIs, no una clave de la plataforma OpenAI, y confirma la cabecera Bearer |
404 | Origen equivocado, falta /v1 o una ruta inventada como /videos/tasks/{id} | Cambia a GET /v1/videos/generations/{id} en el origen que usaste para enviar |
429 | Límite de frecuencia o de concurrencia | Respeta Retry-After cuando esté presente; retrocede con fluctuación aleatoria |
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: failed | La generación no tuvo éxito | Lee error.code y error.message. No repitas un payload rechazado por política sin cambios |
5. Precios y retorno de FinOps
- La compatibilidad no cambia la SKU facturable. Se te factura por el ID de modelo del catálogo que envías (
grok-video-1.5ogrok-video-1.0), no por «usar el SDK de OpenAI». - No reutilices precios unitarios de borradores de planificación. La referencia de Grok Video 1.5 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 la facturación de la cuenta.
- Un descubrimiento fallido es barato; una generación duplicada no. Cachea la lista de modelos durante un periodo corto, pero comprueba siempre el estado de la tarea tras un tiempo de espera agotado del cliente antes de crear otro trabajo.
- 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: una URL base compatible no desbloquea grok-video-3; incluye /v1 una vez; consulta /v1/videos/generations/{id}; no des por hecho que existe un helper videos.create del SDK; las finalizaciones de chat no devolverán un MP4.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Apunta tu cliente a
https://api.toapis.com/v1(ohttps://toapis.cn/v1en China continental) conAuthorization: Bearer. - Llama a
GET /v1/models?type=videoy registra los ID exactos de Grok Video que ve tu clave. - Haz una prueba rápida de
POST /v1/videos/generationscongrok-video-1.5yvideo_generation_mode: "text_to_video", y luego consulta el mismo id. - Siguiente paso: la guía práctica de Grok Video para los detalles de modo y de campos de imagen, y la guía del modelo Grok Video 1.5 para el estado del catálogo en vivo.







