Al final de esta guía, podrás llamar a la API de Lotes de OpenAI para ejecutar miles de solicitudes de modelos como un único trabajo asíncrono y obtener cada resultado con un 50% de descuento. Empaquetarás tus prompts en un archivo JSONL, enviarás un lote, harás un sondeo hasta que termine y descargarás la salida, luego probarás cada paso en Apidog antes de conectarlo a producción. Si tu trabajo es más interactivo, la ruta síncrona es más adecuada, y puedes probar la API de ChatGPT con Apidog en su lugar.
Qué es la API de Lotes y cuándo usarla
La API de Lotes es un endpoint asíncrono para grandes volúmenes de llamadas a modelos que pueden tolerar un retraso. En lugar de una solicitud HTTP por prompt, empaquetas muchas solicitudes en un único archivo JSONL, lo envías como un solo trabajo y realizas un sondeo para su finalización. OpenAI ejecuta el trabajo fuera de las horas pico y devuelve cada resultado en un archivo de salida.
Obtienes dos beneficios concretos. Primero, un descuento fijo del 50% tanto en tokens de entrada como de salida en comparación con la API síncrona. Segundo, un mayor rendimiento, ya que los trabajos por lotes utilizan un pool de límites de tasa separado y no compiten con tu tráfico en vivo. La desventaja es la latencia. OpenAI se compromete a finalizar en 24 horas; muchos trabajos terminan antes, pero no puedes contar con ello.
Recurre al procesamiento por lotes cuando el trabajo es offline y de forma masiva:
- Clasificar o etiquetar un backlog de registros
- Generar embeddings para un corpus completo
- Generación de contenido masivo (descripciones de productos, resúmenes, traducciones)
- Ejecutar suites de evaluación o comparaciones de modelos sobre un conjunto de datos
Omítelo para cualquier cosa que un usuario esté esperando. Las interfaces de usuario de chat, el autocompletado y los agentes en vivo necesitan los endpoints síncronos. Si estás generando muchas configuraciones de modelos o agentes a la vez, el procesamiento por lotes se combina bien con esa carga de trabajo; consulta nuestro tutorial sobre generación de más de 100 configuraciones de agentes con procesamiento por lotes.
Qué necesitas antes de empezar
Todo el flujo abarca dos endpoints, /v1/files y /v1/batches, y cuatro pasos. Esta es la estructura antes de ver las llamadas.
| Paso | Endpoint | Qué sucede |
|---|---|---|
| 1. Cargar | POST /v1/files |
Envía tu archivo .jsonl con purpose: "batch", obtén un ID de archivo |
| 2. Crear | POST /v1/batches |
Envía el ID del archivo con un endpoint y una ventana de finalización |
| 3. Sondear | GET /v1/batches/{id} |
Verifica el status hasta que indique completed |
| 4. Recuperar | GET /v1/files/{id}/content |
Descarga los resultados a través de output_file_id |
Para seguir esta guía, necesitas una clave de API de OpenAI exportada como OPENAI_API_KEY, un archivo JSONL de solicitudes y una herramienta para realizar e inspeccionar las llamadas. Cada paso devuelve un objeto sobre el que puedes realizar aserciones, lo que hace que todo el ciclo de vida sea fácil de probar.
Paso 1: construir y cargar el archivo JSONL
Tu entrada es un archivo JSONL donde cada línea es una solicitud autocontenida. Cada línea necesita cuatro campos: un custom_id que elijas (para que puedas hacer coincidir los resultados con las entradas), el method (POST), la url (el endpoint de destino como /v1/chat/completions) y un body que contiene los parámetros reales de la solicitud.
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}
El custom_id debe ser único dentro del archivo. Los resultados no se devuelven en un orden garantizado, por lo que ese ID es la forma en que vuelves a conectar cada respuesta con su fila de origen. Un solo lote puede contener hasta 50.000 solicitudes y el archivo puede tener hasta 200 MB.
Cárgalo a la API de Archivos con el propósito batch:
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F purpose="batch" \
-F file="@requests.jsonl"
La respuesta contiene un id de archivo (algo como file-abc123). Ese es tu input_file_id para el siguiente paso.
Paso 2: crear el lote
Ahora crea el trabajo. Pasas el input_file_id, el endpoint al que te diriges y la completion_window. Actualmente, completion_window acepta un único valor, "24h".
curl https://api.openai.com/v1/batches \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file-abc123",
"endpoint": "/v1/chat/completions",
"completion_window": "24h",
"metadata": {"job": "sentiment-backfill"}
}'
El campo endpoint debe coincidir con la url utilizada dentro de tus líneas JSONL. Los destinos admitidos incluyen /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions y /v1/moderations, entre otros. El objeto metadata opcional contiene hasta 16 pares clave-valor, lo cual es útil para etiquetar trabajos que querrás filtrar más tarde.
La llamada devuelve un objeto de lote. Los campos que más te interesarán son:
{
"id": "batch_abc123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"input_file_id": "file-abc123",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"request_counts": { "total": 0, "completed": 0, "failed": 0 },
"created_at": 1733452800,
"metadata": { "job": "sentiment-backfill" }
}
Paso 3: sondear el estado del lote
Un lote nuevo comienza en validating. A partir de ahí, pasa por un conjunto de estados documentados. Sondea GET /v1/batches/{batch_id} y lee el campo status.
| Estado | Significado |
|---|---|
validating |
El archivo de entrada se está verificando antes de que comience la ejecución |
in_progress |
Las solicitudes están siendo procesadas |
finalizing |
La ejecución finalizó y el archivo de salida se está preparando |
completed |
Terminado; los resultados están listos para descargar |
failed |
La validación falló; no se ejecutó nada |
expired |
La ventana de 24 horas se cerró antes de que todas las solicitudes terminaran |
cancelling / cancelled |
Solicitaste una cancelación |
El objeto request_counts (total, completed, failed) te proporciona el progreso en vivo mientras el estado se mantiene en in_progress. No hay un webhook que esperar aquí, por lo que sondear en un intervalo sensible (cada pocos minutos, no cada segundo) es el patrón correcto. También puedes cancelar un trabajo en ejecución con POST /v1/batches/{batch_id}/cancel si lo enviaste por error.
Paso 4: recuperar la salida
Cuando el status indica completed, el objeto del lote contiene un output_file_id. Descarga el contenido de ese archivo a través de la API de Archivos:
curl https://api.openai.com/v1/files/file-output456/content \
-H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl
La salida es de nuevo JSONL, una línea por solicitud. Cada línea reproduce el custom_id que estableciste, más un objeto response que contiene el código de estado y el cuerpo. Cualquier solicitud que haya tenido errores aparecerá en el archivo referenciado por error_file_id, así que verifica ambos. Asocia los resultados con las entradas por custom_id, no por el orden de las líneas.
Ten en cuenta los compromisos de costo y ventana de tiempo
Las cuentas son sencillas: ahorras un 50% en tokens y aceptas un tiempo de respuesta de hasta 24 horas. Para una reposición única o un trabajo nocturno, es una decisión fácil. Para una función en la ruta crítica de tu producto, no lo es.
Algunas notas prácticas:
- El descuento se aplica tanto a los tokens de entrada como a los de salida, en todos los modelos compatibles.
- La ventana de 24 horas es un límite máximo, no un objetivo. Planifica para el peor de los casos; si un trabajo llega a
expired, las solicitudes que sí finalizaron aún se facturan y devuelven, y el resto no. - Los trabajos por lotes utilizan un límite de tokens en cola separado, por lo que un lote grande no afectará los límites de tasa de los que depende tu tráfico en vivo. Si ya estás alcanzando los límites, nuestra guía sobre límites de tasa de la API de GPT y cómo probarlos cubre el lado síncrono.
- Los tokens a mitad de precio aún suman en volumen. Realiza un seguimiento del gasto por trabajo usando la etiqueta
metadatapara poder atribuir el costo más tarde; aquí tienes un manual de atribución de costos para el gasto en OpenAI.
Cómo probarlo en Apidog
La API de Lotes es más propensa a errores que una sola llamada de chat, porque los modos de fallo se distribuyen entre archivos, formato JSONL y un bucle de sondeo. Una línea mal formada en un archivo de 50.000 solicitudes hace que falle toda la carga, y no lo sabrás hasta que se ejecute la validación. Probar los endpoints del ciclo de vida antes de automatizarlos te ahorra ese viaje de ida y vuelta.
Apidog es una plataforma de API donde puedes ejecutar cada paso como una solicitud, encadenarlos y realizar aserciones sobre las respuestas. Prueba y simula los endpoints; no es un SDK de OpenAI. Una configuración realista se ve así:
- Primero, valida la estructura JSONL. Antes de cargar cualquier cosa, confirma que cada línea contiene
custom_id,method,urlybody, y quebody.modely los mensajes están presentes. Detectar un campo faltante localmente es más barato que un lote fallido. - Ejecuta la carga multipart. Envía
POST /v1/filesconpurpose=batchy tu archivo, luego captura eliddevuelto en una variable de entorno. - Crea el lote y realiza aserciones sobre el objeto. Ejecuta
POST /v1/batches, luego verifica questatusseavalidatingy queendpointcoincida con lo que enviaste. Las aserciones visuales de Apidog te permiten verificar esos campos sin escribir scripts. - Sondea y recupera. Llama a
GET /v1/batches/{id}en un bucle, verifica cuandostatusse convierta encompleted, luego extraeoutput_file_idy descarga los resultados. - Prueba las rutas de cancelación y error. Envía un archivo deliberadamente roto y confirma que obtienes un estado
failed, y pruebaPOST /v1/batches/{id}/cancelpara que tu manejo de errores sea real, no asumido.
Dado que el archivo de salida llega más tarde, también puedes configurar una API simulada que devuelva un objeto de lote completado de ejemplo y un archivo de resultados predefinido. Esto te permite construir y probar tu lógica de recuperación y análisis sin esperar un trabajo real de 24 horas, y sin gastar tokens durante el desarrollo. Cuando tu equipo trabaja primero con la especificación, también puedes generar una colección de pruebas directamente desde una especificación OpenAPI y mantener los endpoints por lotes bajo cobertura de regresión en CI.
Preguntas frecuentes
¿Cuánto tiempo tarda realmente un lote?
OpenAI se compromete a completar un lote en 24 horas. En la práctica, muchos trabajos terminan antes, pero la garantía es el límite máximo de 24 horas, así que construye tu sistema en torno a eso. Si la ventana se cierra con el trabajo inconcluso, el lote pasa a expired y solo las solicitudes completadas se devuelven y facturan.
¿Cuál es el descuento real y es acumulable?
La API de Lotes ofrece un descuento fijo del 50% frente a los endpoints síncronos, tanto en tokens de entrada como de salida. Es la mayor palanca de costos que OpenAI ofrece para cargas de trabajo offline. Si intentas atribuir ese gasto a características o trabajos, el manual de atribución de costos muestra cómo desglosarlo.
¿Qué endpoints puedo ejecutar en un lote?
Estableces el objetivo tanto en la url JSONL como en el campo endpoint del lote, y deben coincidir. Los destinos admitidos incluyen /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions y /v1/moderations, además de los endpoints de imagen y video. Consulta la documentación actual para ver la lista completa, ya que OpenAI la actualiza con el tiempo.
¿Por qué mis resultados están desordenados?
No están ordenados, por diseño. El JSONL de salida no conserva el orden de las líneas de entrada, que es exactamente la razón por la que cada solicitud necesita un custom_id único. Asocia los resultados con las entradas utilizando ese ID. Si dos líneas comparten un custom_id, no puedes distinguir sus respuestas de forma fiable.
Conclusión
Ahora tienes el flujo completo: empaqueta tus prompts en un archivo JSONL, cárgalo, crea el lote, sondea el estado y recupera la salida, todo a la mitad del costo de los tokens dentro de una ventana de 24 horas. Cada paso devuelve un objeto que puedes verificar, así que una vez que la estructura JSONL y el bucle de sondeo sean correctos, el resto es mecánico.
Antes de automatizarlo, ejecuta el ciclo de vida manualmente. Descarga Apidog para validar tu archivo de solicitud, probar los endpoints de carga, creación, sondeo y cancelación, y realizar aserciones sobre los campos del objeto de lote para que una línea mal formada nunca te cueste un viaje de ida y vuelta de 24 horas.