Saltar al contenido principal
La API Batch te permite enviar grupos de solicitudes como un solo trabajo que se procesa de forma asíncrona. Esto es útil cuando necesitas ejecutar muchas solicitudes y no requieres resultados inmediatos — por ejemplo, realizar evaluaciones, generar embeddings para un gran conjunto de datos o clasificar contenido en masa. Las solicitudes por lotes se ejecutan dentro de una ventana de finalización de 24 horas y tienen límites de velocidad separados y más altos que las llamadas síncronas a la API.

Endpoints compatibles

Todas las solicitudes en un solo lote deben dirigirse al mismo endpoint.

Ciclo de vida

Un lote pasa por estos estados:

Paso 1 — Prepara el archivo de entrada

Crea un archivo JSONL donde cada línea sea una solicitud. Cada línea tiene cuatro campos:
Un solo lote puede contener hasta 10,000 solicitudes.

Paso 2 — Sube el archivo de entrada

Sube el archivo JSONL usando la API de Archivos con purpose: "batch".

Paso 3 — Crea el lote

Pasa el ID del archivo subido, el endpoint de destino y la ventana de finalización.
También puedes adjuntar metadatos para tu propio seguimiento:

Paso 4 — Consulta el estado del lote

Consulta el lote hasta que alcance un estado terminal.
Aquí tienes un ayudante para hacer polling y esperar a que el lote termine:

Paso 5 — Descarga los resultados

Una vez que el lote esté completed, descarga el archivo de salida. Es un archivo JSONL donde cada línea contiene el custom_id que proporcionaste, la respuesta y cualquier error.
Cada línea en el archivo de salida tiene esta estructura:
Si una solicitud falló, response es null y error contiene los detalles:
Si alguna solicitud falló, el lote también proporciona un error_file_id que contiene solo las entradas fallidas.

Cancelar un lote

Cancela un lote que aún está en progreso. Las solicitudes que ya se hayan completado permanecen en la salida.
El lote pasa a cancelling mientras terminan las solicitudes en curso, y luego a cancelled.

Listar lotes

Recupera todos los lotes de la cuenta actual, del más reciente al más antiguo. Soporta paginación.
Usa el parámetro after con un ID de lote para paginar los resultados.

Ejemplo: embeddings por lote

El mismo flujo funciona para embeddings. Cambia el url en cada línea del JSONL y el endpoint al crear el lote.

Errores de validación

Si el archivo de entrada tiene problemas de formato, el lote pasa a failed inmediatamente. Causas comunes:
  • JSON inválido — una línea no es un JSON válido.
  • Campos faltantes — falta custom_id, method, url o body en una línea.
  • Método incorrectomethod debe ser "POST".
  • URL no coincide — el url de una línea no coincide con el endpoint declarado al crear el lote.
  • custom_id duplicado — cada custom_id debe ser único dentro del archivo.
Consulta batch.errors.data para ver los mensajes de error específicos y los números de línea.

Ver también