Ir al contenido principal
Español— Elegir un idioma
Menú

SDK de xAI y sondeo automático

Lección 11 de 12 Actualizado el 2 de noviembre de 2026 Intermedio
En esta página
  1. Simplifica el sondeo con el SDK
  2. Una única llamada en lugar de un bucle
  3. Gestiona los errores en origen
  4. Edición y extensión, misma facilidad
  5. Nunca dejes un vídeo en la nube
  6. Genera varios vídeos a la vez
  7. ¿Deberías abandonar el sondeo manual?
  8. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de vídeo de xAI y el código de xai-sdk 1.21.0: los métodos se llaman client.video.generate y client.video.extend (la edición usa generate con video_url), el resultado expone url, el retraso se configura mediante un timedelta y el intervalo de sondeo predeterminado es de un segundo. await requiere el cliente asíncrono AsyncClient, y la excepción VideoGenerationError se importa desde xai_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.

ErrorCausaAcción recomendada
VideoGenerationErrorFallo 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
TimeoutErrorTiempo de espera del lado del cliente superadoAumenta el timeout o reduce la duración
RuntimeErrorSolicitud diferida caducada o completada sin resultadoReinicia la generación
grpc.RpcErrorError de transporte del SDK, incluidos límites de tasa (código RESOURCE_EXHAUSTED) y problemas de claveEspacia 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.

AspectoSondeo manualSDK
ComplejidadAltaBaja
Gestión de erroresPor implementarIntegrada
Tiempo de esperaPor implementar10 min por defecto, configurable
Intervalo de sondeoA elegir1 s por defecto, configurable
FlexibilidadTotalEstándar (o start y get)
DependenciaNingunaSDK 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.generate enví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 generate con video_url; la extensión usa client.video.extend
  • VideoGenerationError (de xai_sdk.video), TimeoutError y RuntimeError distinguen los fallos; los límites de tasa llegan como grpc.RpcError
  • Descarga siempre el vídeo inmediatamente después de la generación (URL temporales)
  • El cliente asíncrono y asyncio.gather paralelizan un lote, dentro del límite de tasa de tu nivel