SDK de xAI y sondeo automático
En esta página
Actualizado el 2 de noviembre de 2026 según la documentación de vídeo de xAI y el código de
xai-sdk1.21.0: los métodos se llamanclient.video.generateyclient.video.extend(la edición usagenerateconvideo_url), el resultado exponeurl, el retraso se configura mediante untimedeltay el intervalo de sondeo predeterminado es de un segundo.awaitrequiere el cliente asíncronoAsyncClient, y la excepciónVideoGenerationErrorse importa desdexai_sdk.video. La versión anterior llamaba a métodos y a un módulo de excepciones que no existen. Fuentes: Generación de vídeo · Edición de vídeo · Extensión de vídeo · xai-sdk-python.
Simplifica el sondeo con el SDK
En la lección anterior escribiste un bucle de sondeo a mano. Es un ejercicio útil para entender el ciclo de vida de la generación, pero también son treinta líneas de código que hay que mantener en cada proyecto, con su propia gestión de tiempos de espera, casos de fallo y conversiones de estado. El SDK oficial de Python de xAI (pip install xai-sdk) encapsula todo esto: tú envías la solicitud y él se encarga de la espera.
Una única llamada en lugar de un bucle
El método client.video.generate agrupa el envío, el seguimiento y la recuperación. Solo devuelve el control cuando el vídeo está listo o lanza una excepción si algo ha ido mal.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Generación de texto a vídeo con sondeo automático
video = client.video.generate(
prompt="Un amanecer sobre los Alpes, time-lapse acelerado",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Duración: {video.duration} s, modelo: {video.model}")
Detrás de estas pocas líneas, el SDK hace exactamente lo que codificaste antes: enviar la solicitud, sondear el estado cada segundo por defecto y, a continuación, devolver el resultado o lanzar una excepción según el resultado.
Hay un ajuste que merece tu atención desde el despliegue: por defecto, el SDK espera hasta 10 minutos antes de rendirse. Eso es cómodo para un script de producción nocturno, pero demasiado largo para una petición web donde un usuario está esperando una respuesta. Los parámetros timeout e interval, ambos objetos timedelta, establecen el límite y el ritmo:
from datetime import timedelta
video = client.video.generate(
prompt="Tu descripción",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # 5 minutos máx.
interval=timedelta(seconds=5), # una comprobación cada 5 segundos
)
Si quieres mantener el control sobre la espera, por ejemplo para informar del progreso, client.video.start envía la solicitud y devuelve su request_id, que client.video.get consulta después.
Gestiona los errores en origen
El SDK distingue los fallos, lo que te evita tener que analizar cadenas de texto para averiguar qué ha ocurrido:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Tu descripción",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Vídeo listo: {video.url}")
except VideoGenerationError as e:
print(f"Generación fallida [{e.code}]: {e.message}")
except TimeoutError:
print("Tiempo de espera superado: aumenta el timeout o simplifica la solicitud")
Cada error requiere una reacción distinta; confundirlos lleva a bucles de reintento inútiles o, peor aún, a generaciones facturadas que no producen nada.
| Error | Causa | Acción recomendada |
|---|---|---|
VideoGenerationError | Fallo señalado por la API: prompt rechazado, origen no válido, servicio saturado… (code, message) | Lee el código: corrige la solicitud o reintenta más tarde si el servicio no estaba disponible |
TimeoutError | Tiempo de espera del lado del cliente superado | Aumenta el timeout o reduce la duración |
RuntimeError | Solicitud diferida caducada o completada sin resultado | Reinicia la generación |
grpc.RpcError | Error de transporte del SDK, incluidos límites de tasa (código RESOURCE_EXHAUSTED) y problemas de clave | Espacia las solicitudes con retroceso exponencial o comprueba la clave |
El SDK usa gRPC: un límite de tasa superado no aparece aquí como un código HTTP 429, sino como un grpc.RpcError con el código RESOURCE_EXHAUSTED.
Edición y extensión, misma facilidad
La edición no tiene un método dedicado: es generate con un vídeo de origen, pasado como video_url (vídeo de hasta 8,7 segundos, misma duración de salida, 720p máx.).
video = client.video.generate(
prompt="Transforma la escena al estilo anime japonés",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
La extensión prolonga una secuencia de 2 a 15 segundos con un segmento de 2 a 10 segundos y devuelve el vídeo completo:
video = client.video.extend(
prompt="Continúa la escena con un paneo a la derecha",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Observa la diferencia con la API REST: el SDK toma el vídeo como parámetro video_url, mientras que el cuerpo JSON espera un objeto video con su propiedad url.
Nunca dejes un vídeo en la nube
El SDK no cambia nada respecto a la naturaleza temporal de las URL de resultado. Si tu código solo muestra video.url, has pagado una generación que pronto desaparecerá. La mejor práctica es encadenar la generación y la descarga en la misma función, de modo que sea imposible olvidar el paso.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Genera un vídeo y lo guarda localmente (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Descarga inmediata
async with httpx.AsyncClient() as http:
response = await http.get(video.url)
response.raise_for_status()
Path(output_file).write_bytes(response.content)
print(f"Vídeo guardado: {output_file}")
return output_file
Para almacenamiento sin tránsito por tu servidor, el parámetro storage_options de la generación deposita el vídeo en la API de Archivos de xAI, con una caducidad a tu elección.
Genera varios vídeos a la vez
Con el cliente asíncrono, cada llamada es una corrutina, y asyncio.gather lanza todo un lote en paralelo. La opción return_exceptions=True es decisiva aquí: sin ella, una única solicitud rechazada haría fallar todo el lote y perderías los resultados ya obtenidos.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Genera varios vídeos en paralelo."""
client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
tasks = [
client.video.generate(
prompt=req["prompt"],
model="grok-imagine-video-1.5",
duration=req.get("duration", 5),
aspect_ratio=req.get("aspect_ratio", "16:9"),
)
for req in requests
]
results = await asyncio.gather(*tasks, return_exceptions=True)
for i, res in enumerate(results, 1):
if isinstance(res, Exception):
print(f"Solicitud {i} fallida: {res}")
else:
print(f"Solicitud {i} completada: {res.url}")
return results
Dos barreras de seguridad enmarcan esta paralelización. Los envíos consumen tu límite de tasa, contado en solicitudes por segundo según el nivel de tu equipo (10 en el nivel de entrada para modelos de vídeo): para un lote grande, limita la concurrencia con un asyncio.Semaphore. Recuerda también qué hace y qué no hace el paralelismo: no acelera ninguna generación individual, solo reduce el tiempo total del lote.
¿Deberías abandonar el sondeo manual?
No sistemáticamente. La siguiente comparación muestra dónde toma la delantera cada enfoque.
| Aspecto | Sondeo manual | SDK |
|---|---|---|
| Complejidad | Alta | Baja |
| Gestión de errores | Por implementar | Integrada |
| Tiempo de espera | Por implementar | 10 min por defecto, configurable |
| Intervalo de sondeo | A elegir | 1 s por defecto, configurable |
| Flexibilidad | Total | Estándar (o start y get) |
| Dependencia | Ninguna | SDK de xAI |
El sondeo manual mantiene su relevancia en dos situaciones: cuando necesitas un control fino, por ejemplo para informar del progreso a una interfaz en tiempo real o para integrarlo en un sistema de colas existente, y cuando tu contexto de despliegue prohíbe añadir una dependencia extra.
Puntos clave
client.video.generateenvía, espera y devuelve el vídeo (url,duration,model); 10 minutos de tiempo de espera y comprobación cada segundo por defecto- La edición usa
generateconvideo_url; la extensión usaclient.video.extend VideoGenerationError(dexai_sdk.video),TimeoutErroryRuntimeErrordistinguen los fallos; los límites de tasa llegan comogrpc.RpcError- Descarga siempre el vídeo inmediatamente después de la generación (URL temporales)
- El cliente asíncrono y
asyncio.gatherparalelizan un lote, dentro del límite de tasa de tu nivel