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

Crear un lote vacío

Lección 4 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Primer paso: inicialización
  2. La llamada de creación
  3. Implementación en Python
  4. Implementación en JavaScript
  5. Límites de tasa de creación
  6. Buenas prácticas
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de xAI: el descuento por lotes es del 20 % en modelos de texto elegibles (no del 50 %), los ejemplos utilizan la API REST y el SDK oficial xai-sdk (client.batch.*; la API de lotes de xAI no usa el formato de OpenAI, por lo que el SDK de OpenAI no aplica), y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: Batch API · Referencia REST · Precios de lotes.

Primer paso: inicialización

Crear un lote es la primera acción concreta de tu flujo de trabajo. Una llamada POST /v1/batches inicializa un contenedor vacío que recibirá tus solicitudes posteriormente. Este paso es deliberadamente mínimo: crea el identificador y prepara el lote en el lado del servidor.

1

POST /v1/batches

Crea un lote con nombre y devuelve su batch_id.

2

Almacenar el batch_id

Guarda el identificador para operaciones posteriores.

3

Añadir las solicitudes

El lote está listo para recibir solicitudes a través de la API.

La llamada de creación

El cuerpo de la solicitud contiene un único campo obligatorio, name:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

La respuesta contiene el batch_id, las fechas de creación y caducidad, y los contadores del lote, aún a cero (ejemplo extraído de la referencia de la API):

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "customer_review_analysis",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Implementación en Python

El SDK oficial se instala con pip install xai-sdk (versión 1.21.0 a fecha de 2 de noviembre de 2026; requiere Python 3.10 como mínimo). Lee la clave desde la variable de entorno XAI_API_KEY:

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Lote creado: {batch_id}")

El batch_id devuelto es la referencia única de tu lote. Consérvalo en una variable, un archivo o una base de datos, según tu arquitectura.

Implementación en JavaScript

Sin necesidad de un SDK, una simple llamada fetch a la API REST es suficiente:

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "customer_review_analysis" })
});

const batch = await response.json();
console.log(`Lote creado: ${batch.batch_id}`);

Límites de tasa de creación

La creación de lotes está limitada a 2 por segundo por equipo; el número total de lotes no tiene límite. En la práctica, rara vez alcanzarás este límite: lo habitual es crear un lote por operación y añadirle todas las solicitudes. Si creas varios en un bucle, espacia las llamadas al menos 500 milisegundos.

Buenas prácticas

Nombra tus lotes con cuidado: el nombre es obligatorio, así que hazlo útil. Un nombre que indique el conjunto de datos y la fecha (customer_reviews_2026_11_02) facilita la búsqueda en la lista de lotes y en la consola de xAI, que también permite hacer un seguimiento visual de los lotes.

Ten en cuenta la caducidad: expire_time indica cuándo dejarán de estar accesibles el lote y sus resultados. Tu proceso de recuperación debe ejecutarse antes de ese momento.

Gestiona los errores de creación: un error de autenticación, un exceso de límite de tasa o un problema de red pueden impedir la creación. Reintenta los errores transitorios con un retraso creciente (retroceso exponencial), pero nunca reintentes errores de autenticación.

Puntos clave

  • Crear un lote es un POST /v1/batches cuyo único campo obligatorio es name
  • La respuesta contiene un batch_id único que debes conservar para el resto del flujo de trabajo
  • En Python, el SDK oficial xai-sdk expone client.batch.create(batch_name=...)
  • El límite es de 2 creaciones por segundo por equipo, sin tope en el número de lotes
  • Vigila expire_time y reintenta solo errores transitorios