Flujo de trabajo asíncrono y sondeo
En esta página
Actualizado el 2 de noviembre de 2026. Basado en la referencia de la API de Vídeo de xAI: la URL se encuentra en
video.url(no envideo_url), una generación tiene solo tres estados (pending,done,failed, este último acompañado de un código de error), y los límites de tasa se expresan en solicitudes por segundo según el nivel del equipo. Fuentes: Generación de vídeo · Referencia de vídeos · Límites de tasa.
Comprende el ciclo de vida del vídeo
Todas las operaciones de vídeo en la API de xAI son asíncronas, y esta característica condiciona la arquitectura de tu aplicación más de lo que podrías esperar a primera vista. Una llamada de chat o una generación de imágenes devuelven un resultado de inmediato; la generación de vídeo, sin embargo, requiere un tiempo de procesamiento considerable y solo devuelve un acuse de recibo. Corresponde a ti implementar el seguimiento: consultar periódicamente el estado de la tarea, detectar su finalización y recuperar el archivo. El ciclo completo consta de cuatro pasos.
Enviar solicitud
POST al endpoint de generación, edición o extensión. Respuesta inmediata con un request_id.
Sondear estado
GET /v1/videos/{request_id} a intervalos regulares. El campo progress va de 0 a 100.
Recuperar resultado
Cuando el estado es done (progress = 100), la URL del vídeo está disponible.
Descargar inmediatamente
La URL del vídeo es temporal. Descárgala lo antes posible.
Comprobar el estado de la generación
El seguimiento implica una sencilla solicitud GET al endpoint de estado, utilizando el identificador recibido al enviar la solicitud.
curl "https://api.x.ai/v1/videos/vid_abc123def456" \
-H "Authorization: Bearer $XAI_API_KEY"
La respuesta expone la siguiente información útil:
- status: el estado actual de la generación
- progress: un entero de 0 a 100 que indica el progreso
- video.url: la URL del vídeo, dentro del objeto
videopresente cuando el estado esdone, junto con su duración (video.duration) - video.respect_moderation: un booleano que indica si el contenido cumple con la política de moderación
- error: en caso de fallo, un código (
invalid_argument,permission_denied,failed_precondition,service_unavailableointernal_error) y un mensaje - usage.cost_in_usd_ticks: el coste de la solicitud, en diez mil millonésimas de dólar
El campo progress merece una nota: no dirige tu lógica de control, que debe basarse siempre en status, pero es oro puro para una interfaz de usuario. Mostrar «62 %» en lugar de un indicador de carga estático cambia por completo la percepción de una espera que puede durar varios minutos.
Tres estados, tres acciones
| Status | Progress | Significado |
|---|---|---|
pending | 0-99 | Generación en curso |
done | 100 | Completada, URL disponible |
failed | ausente | Generación fallida |
Mientras el estado sea pending, la generación continúa: simplemente debes seguir consultando a intervalos regulares, retransmitiendo el progress a tu interfaz. Cuando cambia a done, el vídeo está listo y lo único que queda por hacer es leer video.url y descargar el archivo inmediatamente; estas URLs son temporales y la documentación no especifica su vida útil, lo que prohíbe almacenarlas en una base de datos para usarlas más tarde.
Por último, el estado failed indica un fallo en la producción, y el campo error te dice cuál ha sido. La distinción importa para lo que sigue: service_unavailable (servicio temporalmente sobrecargado) o internal_error justifican reintentar más tarde, mientras que invalid_argument o permission_denied —prompt rechazado, imagen o vídeo de origen no válido— requieren corregir primero la solicitud. El SDK de Python, por su parte, también señala mediante un error una solicitud diferida que ha caducado antes de ser recuperada.
Implementar el sondeo
La versión síncrona cabe en una sola función. Hace un bucle hasta agotar el tiempo de espera, sale anticipadamente en caso de fallo lanzando su código y devuelve la URL tan pronto como el vídeo está listo.
import httpx
import time
def attendre_video(request_id, api_key, timeout=600, intervalle=5):
"""Esperar a que finalice la generación del vídeo."""
headers = {"Authorization": f"Bearer {api_key}"}
debut = time.time()
while time.time() - debut < timeout:
resp = httpx.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
).json()
status = resp.get("status")
progress = resp.get("progress", 0)
if status == "done":
return resp["video"]["url"]
elif status == "failed":
erreur = resp.get("error", {})
raise RuntimeError(f"Generación fallida [{erreur.get('code')}] : {erreur.get('message')}")
print(f"En curso... {progress}%")
time.sleep(intervalle)
raise TimeoutError(f"Tiempo de espera agotado tras {timeout} segundos")
En un servicio que gestiona múltiples solicitudes a la vez, esta versión bloqueante se convierte en un cuello de botella: cada espera inmoviliza un hilo durante minutos. La transposición asíncrona libera el bucle de eventos entre consultas y te permite seguir docenas de generaciones en paralelo.
import httpx
import asyncio
async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
"""Versión asíncrona del sondeo."""
headers = {"Authorization": f"Bearer {api_key}"}
async with httpx.AsyncClient() as client:
debut = asyncio.get_event_loop().time()
while asyncio.get_event_loop().time() - debut < timeout:
resp = await client.get(
f"https://api.x.ai/v1/videos/{request_id}",
headers=headers
)
data = resp.json()
if data["status"] == "done":
return data["video"]["url"]
elif data["status"] == "failed":
raise RuntimeError(f"Generación fallida : {data.get('error')}")
await asyncio.sleep(intervalle)
raise TimeoutError("Tiempo de espera agotado")
Establecer el intervalo de sondeo
Elegir el intervalo equilibra la capacidad de respuesta con el desperdicio de solicitudes. Cinco segundos es un buen compromiso en la mayoría de los casos. Para generaciones largas —de diez a quince segundos de vídeo—, diez o quince segundos entre sondeos son suficientes y reducen el tráfico. Por el contrario, una aplicación interactiva donde el usuario observa una barra de progreso justifica bajar a dos o tres segundos. Sin embargo, por debajo de un segundo no acelerarás nada: la generación avanza a su propio ritmo y solo multiplicarás solicitudes inútilmente.
Puntos clave
- Todas las operaciones de vídeo son asíncronas: POST para enviar, GET para recuperar
- Tres estados posibles: pending, done, failed (con un código de error)
- El campo
progress(0-100) permite seguir el avance - Implementa un tiempo de espera y un intervalo de sondeo adecuados a tu caso de uso
- Las URLs de los vídeos son temporales: descárgalas inmediatamente