API de generación de vídeo Grok Imagine 1.0: endpoints, ámbitos de autenticación y gestión de errores
Modelos objetivo:
grok-imagine-video-official,grok-imagine-video-1.5-official
Endpoint de inferencia:https://api.toapis.com/v1/videos/generations
Relacionado: Guía práctica de Grok Video · Acceso compatible con OpenAI · Generación oficial de Imagine · Extend oficial de Imagine
1. Resumen y panorama del rendimiento
- ID: las solicitudes tituladas en torno a «Grok Imagine 1.0» necesitan las cadenas que ToAPIs publica realmente. La instantánea pública del catálogo fechada 2026-11-10 lista
grok-imagine-video-officialygrok-imagine-video-1.5-official(esas dos también aparecen bajo generación de imágenes y bajoopenai-video). Una comprobación del 2026-11-17 de una ruta de documentacióngrok-imagine-1.0devolvió HTTP 404. - Autenticación: envía
Authorization: Bearer $TOAPIS_API_KEY. Las páginas oficiales no documentan ámbitos OAuth, nombres de permisos granulares ni ningún endpoint de descubrimiento de ámbitos para estas llamadas. - Endpoints: crea con
POST /v1/videos/generations. Consulta conGET /v1/videos/generations/{id}. Extiende la salida del canal oficial conPOST /v1/videos/{video_id}/extend, o conPOST /v1/videos/extendmásvideo_urlscuando solo tienes una URL pública del vídeo. Sube imágenes fijas conPOST /v1/uploads/images. - Capacidades:
grok-imagine-video-officialcubre texto a vídeo, imagen a vídeo y generación con múltiples referencias en480po720p, duración de 1–15 segundos, y extend de 2–10 segundos.grok-imagine-video-1.5-officiales solo imagen a vídeo con primer fotograma, requiere exactamente unaimage, permite1080py no admite extend. - Forma del precio (no hay precio unitario fijo en las páginas de referencia): la salida se factura por segundo según la resolución; cada imagen de entrada se factura por imagen; extend también factura la duración del vídeo de origen. Confirma las tarifas vigentes de la cuenta.
2. Endpoints, autenticación y contratos de modelo
La documentación oficial usa https://toapis.com (y https://toapis.cn para China continental). Otras guías de esta serie usan https://api.toapis.com. Elige un origen y mantenlo coherente. Todas las rutas de abajo usan la misma cabecera Bearer.
| Acción | Método y ruta | Notas del modelo |
|---|---|---|
| Subir una imagen fija | POST /v1/uploads/images | file multipart. JPEG, PNG, WebP o GIF, máximo 30 MB. Lee data.url |
| Crear un vídeo | POST /v1/videos/generations | Ambos ID oficiales de Imagine |
| Consultar estado | GET /v1/videos/generations/{id} | Misma ruta para tareas de generación y de extend |
| Extender desde una tarea previa | POST /v1/videos/{video_id}/extend | Solo grok-imagine-video-official. video_id es el id de la tarea de generación anterior |
| Extender desde una URL pública | POST /v1/videos/extend | Mismo ID oficial; video_urls es obligatorio cuando no hay id en la ruta |
| ID de catálogo | Trabajos documentados | Duración | Resolución | Imágenes | Extend |
|---|---|---|---|---|---|
grok-imagine-video-official | Texto a vídeo, primer fotograma y múltiples referencias | 1–15 segundos (predeterminado 8) | 480p, 720p | image opcional más reference_images; hasta 7 en total | 2–10 segundos (duration predeterminada 6) |
grok-imagine-video-1.5-official | Solo imagen a vídeo con primer fotograma | 1–15 segundos (predeterminado 8) | 480p, 720p, 1080p | image es obligatoria (exactamente un primer fotograma). Los reference_images adicionales siguen contando para el total de 7 imágenes | No admitido |
Los valores de relación de aspecto de las referencias oficiales de Imagine incluyen 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 y 1:1. Envía un valor que hayas confirmado para ese ID y ese canal.
No existe ninguna cadena de ámbito pública documentada para solicitar «generar», «extender» o «subir» por separado. El acceso es lo que la clave API, el grupo de usuarios y la configuración del canal ya permiten. Si una llamada falla por permisos o disponibilidad, revisa la lista de modelos de la clave y la referencia de errores en lugar de añadir un parámetro de consulta scope inventado.

Figura 1: una única clave API Bearer autoriza la carga, la generación o extend y la consulta de estado; el ID oficial 1.5 no añade una rama de extend.
Para la familia Grok Video no oficial (grok-video-1.0 / grok-video-1.5), consulta la guía práctica de Grok Video. Esos ID son otro contrato y no heredan esta ruta de extend.
3. Implementación en producción: cURL y Python
Paso 1: cURL, texto a vídeo en el canal oficial
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Un trabajo con primer fotograma en grok-imagine-video-1.5-official usa la misma ruta, exige "image": "https://example.com/portrait.jpg" y puede fijar "resolution": "1080p". Sustituye la URL de ejemplo por una dirección pública; sube el archivo primero si es local:
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
Paso 2: Python, generar, consultar y extend opcional
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
Para extender desde un MP4 público en lugar de un id de tarea, usa POST /v1/videos/extend con el mismo modelo oficial, prompt, duration y una lista video_urls. No llames a extend con grok-imagine-video-1.5-official.
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. La referencia de errores distingue errores de solicitud, valores de error.reason de tareas fallidas y payloads de webhook.
| Estado HTTP o de tarea | Categoría habitual | Acción recomendada |
|---|---|---|
400 | Campo inválido, image obligatoria ausente en 1.5-official, desbordamiento del recuento de imágenes o extend enviado a un modelo que no lo admite | Revisa el ID oficial exacto, la duración (1–15 al generar, 2–10 al extender), la resolución (1080p solo en 1.5-official) y que todos los valores de medios sean URL públicas |
401 | Clave de API ausente o inválida | Rota la clave y confirma Authorization: Bearer. No añadas un parámetro scope no documentado como solución |
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: queued o in_progress | No es un error | Espera y consulta de nuevo |
status: failed con content_policy_rejected | Revisión de seguridad o de derechos de autor | Revisa el prompt y cada recurso de referencia; una entrada conforme puede aun así producir una salida rechazada |
status: failed con insufficient_user_balance o token_quota_exceeded | Saldo o cuota de tokens | Revisa tanto el saldo como los límites periódicos |
status: failed con generation_timeout, model_unavailable o service_busy | Tiempo de espera agotado o disponibilidad del upstream | Revisa primero el id existente; después reintenta con retroceso solo si la tarea es final |
5. Precios y retorno de FinOps
Las páginas oficiales de generación y de extend de Imagine describen una forma de facturación, no un precio unitario público fijo:
Usa las tarifas que se devuelven para tu cuenta y SKU, no números de borrador.
grok-imagine-video-1.5-officialsiempre incluye un cargo por imagen de entrada, porque la imagen de primer fotograma es obligatoria.- Extend no es una continuación gratuita. La facturación oficial de extend incluye los segundos de extensión generados y la duración del vídeo de origen. Por eso los extend encadenados vuelven a cobrar la longitud creciente de origen: confirma ese comportamiento con una cotización vigente antes de montar un bucle.
- No reutilices precios unitarios ni cifras de SLA de borradores de planificación. 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.
- Haz borradores en
720pcon una duración intermedia, cambia una variable cada vez y nunca reenvíes tras un tiempo de espera agotado del cliente hasta comprobar el estado de la tarea.
6. Preguntas frecuentes
Consulta el bloque de preguntas frecuentes del frontmatter. En resumen: envía grok-imagine-video-official o grok-imagine-video-1.5-official, no grok-imagine-1.0; la autenticación es una clave API Bearer sin matriz pública de ámbitos OAuth; 1.5-official es solo primer fotograma y no puede extender; la duración de extend es de 2 a 10 segundos y factura también la longitud de origen; distingue siempre los errores HTTP de los status: failed.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Confirma que
grok-imagine-video-officialogrok-imagine-video-1.5-officialaparece para tu clave medianteGET /v1/models?type=video. - Haz una prueba rápida de una generación oficial en
720p, consultaGET /v1/videos/generations/{id}y descarga el archivo antes deexpires_at. - Si necesitas una continuación, extiende solo con
grok-imagine-video-officialy unadurationde 2 a 10 segundos, y luego confirma que la cotización incluye la facturación de la duración de origen. - Siguiente paso: la guía oficial del modelo Imagine y la guía oficial del modelo Imagine 1.5 para el estado del catálogo en vivo, y la guía práctica de Grok Video si te referías a la familia no oficial
grok-video-*.







