Flujo de trabajo en cuatro pasos
En esta página
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
xai-sdkoficial (client.batch.*; la API de lotes de xAI no sigue el formato de OpenAI, por lo que el SDK de OpenAI no es aplicable); y la API de Responses tiene prioridad sobre Chat Completions, un punto final heredado en xAI. Fuentes: Batch API · Referencia REST · Precios de lotes.
El ciclo de vida de un lote
Todo lote sigue el mismo ciclo: crear, añadir solicitudes, procesar y recuperar resultados. Comprender este ciclo es esencial antes de pasar a la implementación, ya que cada paso tiene sus propias restricciones y mejores prácticas.
Paso 1: Crear un lote
Todo comienza con una llamada POST /v1/batches, con un campo obligatorio: el nombre del lote. La API devuelve un identificador único (batch_id) que utilizarás para todas las operaciones posteriores.
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 también contiene las fechas de creación y caducidad del lote (create_time, expire_time) y un objeto state cuyos contadores están aún a cero.
Paso 2: Añadir solicitudes
Existen dos métodos:
A través de la API: envías solicitudes con POST /v1/batches/{batch_id}/requests. Cada llamada transporta una lista de solicitudes y puedes seguir añadiéndolas mientras el lote no se cancele. Esta es la vía para lotes que se construyen de forma incremental.
Mediante un archivo JSONL: preparas un archivo que contiene todas tus solicitudes, lo subes a través de la API de Files y luego creas el lote a partir de ese archivo. El lote queda entonces sellado: no es posible añadir más elementos. Esta es la vía para grandes volúmenes preparados con antelación.
Cada solicitud lleva un identificador único dentro del lote: batch_request_id en la API, custom_id en el archivo JSONL. Si lo omites en la API, xAI genera un UUID; proporciona el tuyo propio (un ID de base de datos, por ejemplo): sirve como clave de coincidencia entre tus datos y los resultados, y garantiza que una solicitud se procese solo una vez.
Paso 3: Supervisar el progreso
El procesamiento comienza en cuanto llegan las solicitudes; no existe un paso de “inicio”. Mientras tanto, GET /v1/batches/{batch_id} devuelve el objeto state y sus contadores: num_requests (total), num_pending (pendientes), num_success (correctas), num_error (fallidas) y num_cancelled (canceladas).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Cuando num_pending baja a cero, todas las solicitudes han sido procesadas, con éxito o no. El sondeo periódico es suficiente: unos segundos para un lote de prueba pequeño, unos minutos para un lote grande.
Paso 4: Recuperar resultados
Los resultados se leen con GET /v1/batches/{batch_id}/results, sin esperar a que el lote termine: cada solicitud está disponible en cuanto se procesa. La respuesta está paginada: limit establece el tamaño de la página (máximo 1.000) y el pagination_token devuelto se utiliza para solicitar la página siguiente; está vacío en la última página.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Cada resultado lleva el batch_request_id de su solicitud: esto te permite reconstruir la correspondencia entre tus datos de entrada y las respuestas de Grok.
El flujo de trabajo en la práctica
En una canalización de producción, el flujo de trabajo se traduce generalmente en dos procesos separados:
- Un proceso de envío que crea el lote, prepara y añade solicitudes, y luego almacena el
batch_id - Un proceso de recuperación que comprueba periódicamente los contadores y descarga los resultados a medida que están disponibles
Esta separación te permite integrar la API de lotes en arquitecturas dirigidas por eventos o en canalizaciones de datos existentes (tareas cron, Apache Airflow, colas).
Gestión de errores en el flujo de trabajo
Un lote no tiene un estado global de “correcto” o “fallido”: se lee a través de sus contadores. Una solicitud fallida incrementa num_error y aparece en los resultados con su mensaje de error, sin bloquear a las demás. Por tanto, debes examinar cada resultado y gestionar los fallos caso por caso.
Dos eventos afectan a todo el lote. El primero es la cancelación, por tu parte o por parte de xAI, que entonces lo explica en el campo cancel_by_xai_message. Esto ocurre en particular cuando una línea de un archivo JSONL no es válida. El otro es la caducidad (expire_time), tras la cual los resultados ya no son accesibles: recuéperalos con prontitud.
Puntos clave
- El flujo de trabajo sigue el orden: crear (con un nombre), añadir, supervisar, recuperar
- El identificador de solicitud (
batch_request_id, ocustom_iden JSONL) es tu clave de coincidencia - El progreso se lee en los contadores de
state; todo está procesado cuandonum_pendinges cero - Los resultados están paginados (
limit,pagination_token) y disponibles a medida que se procesan - Los errores se gestionan solicitud por solicitud; la cancelación y la caducidad afectan a todo el lote