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

Gestión de errores y despliegue en producción

Lección 12 de 12 Actualizado el 3 de noviembre de 2026 Intermedio
En esta página
  1. Prepara tu aplicación para producción
  2. Dos familias de errores, dos momentos
  3. Reintentar con inteligencia
  4. Una cola para mantener el ritmo
  5. Verifica tu clave antes de depender de ella
  6. Observa qué ocurre en producción
  7. Puntos clave
  8. Pon a prueba tus conocimientos

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: client.video.generate (no client.videos), el resultado está en url, los fallos se reportan mediante VideoGenerationError con un código (invalid_argument, service_unavailable…), y el límite de tasa se recibe como grpc.RpcError con el código RESOURCE_EXHAUSTED; la clase RateLimitError y el estado expired no existen. Complemento del 3 de noviembre de 2026: el límite de tasa cuenta solicitudes por segundo (10 en el nivel de entrada), no «60 RPM», y el coste real por generación se lee en usage.cost_in_usd_ticks. Fuentes: Generación de vídeo · Límites de tasa.

Prepara tu aplicación para producción

Un script que genera un vídeo en tu máquina y un servicio que produce cientos al día para usuarios reales apenas tienen nada en común. Este último debe gestionar rechazos de moderación, excesos de cuota, incidentes del servidor y URLs caducadas sin perder nunca en silencio una generación facturada. Esta lección cubre los mecanismos que marcan la diferencia: clasificación de errores, estrategia de reintentos, arquitectura de colas y observabilidad.

Dos familias de errores, dos momentos

La primera familia aparece de inmediato, en el momento de la llamada POST. Son errores estrictos de solicitud, y el código HTTP basta para decidir qué hacer.

Código HTTPCausaSolución
400Parámetros no válidos (por ejemplo, una voz desconocida en reference_audios)Corregir la solicitud
401Clave de API no válida o caducadaVerificar la autenticación
429Límite de tasa superado (solicitudes por segundo, según el nivel)Implementar retroceso exponencial (backoff)
500Error del servidorReintentar con retroceso exponencial

La segunda familia se manifiesta mucho más tarde, durante el sondeo (polling), después de que la solicitud haya sido aceptada y la generación haya comenzado.

EstadoCausa probableAcción
failed + invalid_argument o permission_deniedSolicitud o contenido rechazadoModificar el prompt o la fuente
failed + service_unavailable o internal_errorServicio sobrecargado, incidenteReintentar más tarde

Esta distinción no es académica: un 400 debe devolver el control al llamador al instante porque el fallo está en el código, mientras que un estado failed ocurre tras varios minutos de espera y debe gestionarse en el contexto del trabajo (job), no en la solicitud HTTP que lo desencadenó.

Reintentar con inteligencia

La base común es el retroceso exponencial con algo de aleatoriedad (jitter). Duplicar el retraso da tiempo a que se resuelva un incidente transitorio, y la aleatoriedad evita que todos tus procesos reintenten al mismo instante tras un pico de tráfico, un fenómeno que convierte una microinterrupción en un fallo duradero.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Ejecuta una función con reintentos y retroceso exponencial."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Retroceso exponencial con jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Intento {attempt + 1} fallido: {e}. Reintentando en {delay:.1f}s")
            await asyncio.sleep(delay)

Sin embargo, este esquema genérico no basta, porque no todos los errores merecen la misma paciencia. Un exceso de cuota se resuelve esperando un minuto completo; un rechazo por moderación nunca se resolverá, y reintentar equivale a pagar varias veces por el mismo fallo. La siguiente función diferencia los casos.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Códigos de fallo que un reintento no solucionará
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Generación de vídeo con reintentos específicos (client: xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # solicitud o contenido rechazado: corregir antes de relanzar
            await asyncio.sleep(5 * (attempt + 1))  # servicio sobrecargado, incidente
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # límite de tasa: retroceso
        except TimeoutError:
            if is_last:
                raise
            # Dar más tiempo al siguiente intento
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Una cola para mantener el ritmo

En cuanto tu servicio reciba solicitudes de múltiples usuarios, debes desacoplar la recepción de solicitudes de su ejecución y, sobre todo, limitar la concurrencia para mantenerte bajo el límite de tasa de tu nivel. Una cola emparejada con un semáforo satisface ambas necesidades: los trabajos se acumulan libremente, pero como máximo diez se ejecutan a la vez.

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Añade una generación a la cola."""
        self.queue.append((job_id, params))

    async def process(self):
        """Procesa todas las generaciones pendientes."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Ejecuta una generación con control de concurrencia."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

Ten en cuenta que cada trabajo mantiene su resultado en results, sea éxito o fallo: una generación que desaparece sin dejar rastro es un incidente que nadie puede diagnosticar.

El segundo reflejo arquitectónico concierne al almacenamiento. Dado que las URLs de los vídeos son temporales, la descarga debe ser automática e inmediata, con una nomenclatura con marca de tiempo que garantice que no haya colisiones entre dos generaciones simultáneas.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Descarga y guarda un vídeo generado."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Verifica tu clave antes de depender de ella

El punto final GET /v1/api-key te informa sobre el estado de tu clave. Llamarlo al arrancar el servicio evita descubrir una clave bloqueada tras veinte solicitudes fallidas, mientras tus usuarios esperan.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("Clave de API o equipo bloqueados, o clave deshabilitada")

Observa qué ocurre en producción

Cinco indicadores bastan para pilotar un servicio de generación de vídeo. La tasa de éxito, es decir, la proporción de generaciones que terminan en done, mide la salud general. El tiempo medio de generación, medido entre el envío y el estado done, sirve para calibrar tus tiempos de espera e informar a tus usuarios. La tasa de error desglosada por tipo —failed por código de error, tiempo de espera agotado, límite de tasa— te indica dónde centrar los esfuerzos: un aumento de los tiempos de espera agotados sin un aumento de los failed señala, por ejemplo, generaciones más lentas que tu plazo de espera, no fallos. El coste acumulado, obtenido sumando el campo usage.cost_in_usd_ticks de cada resultado (un dólar equivale a 10 mil millones de ticks), o alternativamente multiplicando las duraciones generadas por el precio por segundo del modelo, debe monitorizarse a diario. Por último, el uso de la cuota, en solicitudes por segundo respecto al límite de tu nivel (10 en el nivel de entrada para modelos de vídeo), anticipa la saturación antes de que se traduzca en errores 429.

Estas métricas se construyen naturalmente a partir de un registro estructurado, donde cada generación deja una línea utilizable por tu herramienta de análisis.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

Antes de abrir tu servicio al público, revisa todo el conjunto desde el principio. Los reintentos con retroceso exponencial y aleatoriedad deben estar implementados, y la concurrencia limitada por un semáforo para mantenerse bajo el límite de tasa. Las descargas de vídeo deben activarse automáticamente en cuanto estén listas, sin depender de acción humana. Cada generación debe dejar una línea de registro que lleve su request_id, estado y coste; de lo contrario, la tasa de error y el tiempo medio de generación seguirán siendo inverificables. Comprueba el estado de la clave de API al arrancar en lugar de hacerlo ante el primer fallo. Y establece un presupuesto con alertas de exceso: a 0,05 $ por segundo, un bucle de reintentos sin límites consume más rápido de lo que crees.

Precios verificados el 3 de noviembre de 2026: los precios evolucionan con regularidad; antes de cualquier cálculo presupuestario, verifica la tarifa actual en la página oficial de modelos y precios de xAI.

Puntos clave

  • Los errores se dividen en sincrónicos (solicitud) y asincrónicos (generación)
  • No todos los errores merecen un reintento: la moderación es definitiva
  • Usa un semáforo para limitar las generaciones concurrentes
  • Las URLs temporales requieren una descarga inmediata y sistemática
  • Rastrea las métricas de coste, éxito y tiempo de generación para pilotar tu servicio

Pon a prueba tus conocimientos

Vídeo generativo en producción: valida el flujo de trabajo completo.

1. ¿Cuáles son las particularidades de un prompt de vídeo?

Respuesta: Describe la acción y el movimiento, no solo la escena: sujeto, desplazamiento, ambiente, encuadre; la dimensión temporal es lo que distingue el prompt de vídeo del de imagen.

2. ¿Qué permite la función imagen-a-vídeo?

Respuesta: Animar una imagen existente o introducir personas y productos dados en una nueva escena usando imágenes de referencia y, en grok-imagine-video-1.5, fijar la primera, la última o las imágenes clave: tu identidad visual se convierte en un punto de partida, no en una casualidad.

3. Edición y extensión: ¿qué usos tienen?

Respuesta: /videos/edits modifica un vídeo generado, /videos/extensions lo prolonga; ambos se combinan para construir secuencias largas mediante iteraciones.

4. ¿Por qué es asíncrono el flujo de trabajo?

Respuesta: La generación de vídeo lleva tiempo: envías un trabajo, sondeas su estado y luego recuperas el resultado; el SDK de xAI automatiza este sondeo.

5. ¿Qué hay que planificar para producción?

Respuesta: Gestión de errores y trabajos fallidos, descarga inmediata de los resultados y seguimiento de costes (resolución, duración, iteraciones); el vídeo es la modalidad más cara: debe presupuestarse.

Prompt temporal, referencia visual, asíncrono dominado: el vídeo generativo se convierte en una canalización, no en una lotería.