Batch API OpenAI: procesa miles de solicitudes de forma asíncrona
Batch API OpenAI permite enviar grandes volúmenes de solicitudes para procesarlas de forma asíncrona, sin depender de respuestas inmediatas. Puedes preparar un archivo JSONL, subirlo a OpenAI, crear un batch y recuperar los resultados una vez finalizado. Es especialmente útil para procesamiento masivo, clasificación, generación, embeddings y trabajos offline.
¿Qué es Batch API OpenAI?
Batch API OpenAI permite agrupar muchas solicitudes de API dentro de un archivo JSONL y ejecutarlas de forma asíncrona. En lugar de enviar cada request individualmente y esperar su respuesta en tiempo real, creas un batch que OpenAI procesa dentro de una ventana definida.
Qué permite hacer Batch API OpenAI
Batch API está pensado para workloads que no necesitan respuesta instantánea.
Procesar volumen
Ejecutar grandes conjuntos de solicitudes dentro de un solo trabajo.
Reducir costos
Batch utiliza precios más bajos que el procesamiento Standard.
Trabajo asíncrono
No necesitas mantener una conexión abierta esperando cada respuesta.
Usar JSONL
Cada línea representa una solicitud independiente dentro del batch.
Separar errores
Los resultados correctos y errores pueden recuperarse mediante archivos separados.
Automatizar procesos
Ideal para tareas nocturnas, migraciones o procesamiento programado.
Cómo funciona Batch API OpenAI
El proceso comienza preparando las requests y termina descargando los resultados.
Preparas el archivo
Cada línea contiene una solicitud completa de API.
Creas el trabajo
Subes el archivo y creas un nuevo batch.
Recuperas resultados
Cuando finaliza, descargas los outputs y errores.
Flujo completo de Batch API OpenAI
Un batch normalmente sigue cinco etapas principales.
Crear el archivo JSONL con las requests.
Subir el archivo
utilizando
purpose: "batch".
Crear un batch
utilizando
el input_file_id.
Consultar el estado del procesamiento.
Descargar el archivo de resultados.
Cómo preparar el archivo JSONL para Batch API
Cada línea debe representar una solicitud independiente.
Ejemplo con Responses API
{"custom_id":"req-001","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.6-sol","input":"Resume este texto en tres puntos."}}
{"custom_id":"req-002","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.6-sol","input":"Clasifica esta opinión como positiva, neutral o negativa."}}
{"custom_id":"req-003","method":"POST","url":"/v1/responses","body":{"model":"gpt-5.6-sol","input":"Extrae los conceptos principales del texto."}}Utiliza un identificador único por request para relacionar fácilmente cada output con el registro original.
Campos de cada request del archivo JSONL
| Campo | Función |
|---|---|
custom_id |
Identificador que tú asignas a la solicitud |
method |
Método HTTP de la request |
url |
Endpoint que procesará esa solicitud |
body |
Payload normal que enviarías al endpoint |
Subir el archivo para Batch API OpenAI
Antes de crear el batch, debes subir el JSONL mediante Files API.
Subir batch.jsonl
from openai import OpenAI
client = OpenAI()
batch_file = client.files.create(
file=open("batch.jsonl", "rb"),
purpose="batch"
)
print(batch_file.id)Batch API admite actualmente archivos JSONL de hasta 200 MB.
Crear un batch
Una vez obtenido el file ID, puedes crear el trabajo asíncrono.
Crear Batch API
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/responses",
completion_window="24h"
)
print(batch.id)La ventana de procesamiento actual es 24h
Batch API no está pensado para respuestas en tiempo real.
completion_window
El valor soportado
actualmente para
completion_window
es 24h.
Esto significa
que el trabajo
debe completarse
dentro de esa ventana.
Puede terminar antes. Las 24 horas representan la ventana máxima definida por Batch API.
Qué endpoints admite Batch API OpenAI
El endpoint indicado al crear el batch debe coincidir con las requests del archivo JSONL.
| Endpoint | Uso |
|---|---|
/v1/responses |
Responses API |
/v1/chat/completions |
Chat Completions |
/v1/embeddings |
Generación de embeddings |
/v1/completions |
Completions legacy |
/v1/moderations |
Moderation |
Los batches
para /v1/embeddings
están restringidos
actualmente
a un máximo
de 50.000 inputs
de embeddings
sumando todas
las requests del batch.
Consultar el estado de un batch
Después de crear el trabajo, puedes recuperar el objeto batch mediante su ID.
Consultar progreso
batch = client.batches.retrieve(
"batch_abc123"
)
print(batch.status)Estados de un batch
El objeto Batch permite conocer en qué etapa se encuentra el trabajo.
| Estado | Significado general |
|---|---|
validating |
El archivo y las solicitudes se están validando |
in_progress |
Las solicitudes están siendo procesadas |
finalizing |
OpenAI está preparando los resultados finales |
completed |
El batch terminó correctamente |
failed |
El batch falló |
expired |
No terminó dentro de la ventana disponible |
cancelling |
La cancelación está en proceso |
cancelled |
El batch fue cancelado |
request_counts muestra cuánto se ha procesado
Solicitudes completadas y fallidas
{
"request_counts": {
"total": 10000,
"completed": 9850,
"failed": 150
}
}Descargar los resultados del batch
Cuando el batch
termina,
el objeto puede incluir
un output_file_id.
Recuperar el archivo de salida
file_response = client.files.content(
batch.output_file_id
)
print(file_response.text)No dependas exclusivamente del orden de las líneas. El identificador personalizado permite emparejar cada respuesta con su request original.
error_file_id en Batch API
Un batch puede completar algunas requests correctamente y fallar en otras.
Errores separados de los outputs exitosos
El objeto Batch puede proporcionar un archivo específico con información correspondiente a las solicitudes que produjeron errores.
Guarda los
custom_id
fallidos
y crea un nuevo batch
únicamente con
las requests
que realmente
necesitan reintentarse.
Listar batches de la organización
Batch API permite consultar trabajos anteriores mediante paginación.
GET /v1/batches
La API permite
listar batches
y utilizar parámetros
como limit
y after
para recorrer
los resultados.
Cancelar un batch
Si un trabajo ya no es necesario, puedes solicitar su cancelación mientras sigue activo.
Detener procesamiento innecesario
Después de solicitar
la cancelación,
el batch puede pasar
temporalmente
por el estado
cancelling
antes de quedar
cancelled.
Batch API vs solicitudes normales
La principal diferencia está en la prioridad entre velocidad y costo.
| Aspecto | Batch API | API Standard |
|---|---|---|
| Respuesta inmediata | No | Sí |
| Procesamiento | Asíncrono | Síncrono o streaming |
| Ventana | Hasta 24h | En tiempo de solicitud |
| Precio | 50% de Standard en modelos compatibles | Tarifa Standard |
| Uso ideal | Procesamiento masivo offline | Apps interactivas |
Batch API vs Background Mode
Ambas opciones son asíncronas, pero responden a necesidades diferentes.
| Aspecto | Batch API | Background Mode |
|---|---|---|
| Unidad de trabajo | Muchas requests | Una respuesta larga o compleja |
| Archivo JSONL | Sí | No |
| Objetivo | Volumen | No bloquear una operación larga |
| Resultado | Archivo batch | Response object |
Cuánto cuesta Batch API OpenAI
Batch está pensado para reducir el costo de workloads que pueden esperar.
Batch cuesta la mitad de Standard
En los modelos que publican tarifas Batch, OpenAI cobra actualmente el 50% de la tarifa Standard correspondiente.
Si una tarea no necesita una respuesta inmediata, procesarla mediante Batch puede producir un ahorro importante a escala.
Ver precios OpenAI API →Casos de uso de Batch API OpenAI
Batch API resulta especialmente útil en procesos que pueden ejecutarse fuera del flujo interactivo del usuario.
Clasificación: procesar miles de comentarios o documentos.
Resúmenes: generar resúmenes de grandes colecciones de textos.
Embeddings: procesar grandes conjuntos de contenido.
Moderación: analizar contenido de forma masiva.
Ecommerce: generar descripciones, categorías o atributos para catálogos.
SEO: procesar metadatos o clasificar grandes colecciones de contenido.
Procesar 50.000 productos con Batch API
Imagina un ecommerce que necesita categorizar decenas de miles de productos.
Exportas los productos desde la base de datos.
Generas una línea JSONL por producto.
Creas el batch.
Esperas a que finalice.
Importas
los resultados
utilizando
custom_id.
Medir tokens utilizados por un batch
El objeto Batch actual puede incluir información agregada de uso.
Uso agregado del trabajo
Para batches creados desde septiembre de 2025, OpenAI puede incluir métricas agregadas de input, output y total de tokens en el objeto Batch.
Batch queue limits
Batch utiliza límites específicos separados de las solicitudes interactivas normales.
El límite depende del modelo y usage tier
Las fichas de modelos publican un Batch queue limit que puede variar considerablemente según tu tier.
Para workloads Batch, revisa específicamente la capacidad de cola publicada para el modelo que estés utilizando.
Ver límites OpenAI API →Cómo diseñar un buen workflow con Batch API OpenAI
Genera un
custom_id
único y estable
para cada request.
Valida el JSONL antes de subirlo.
Guarda
batch_id
e input_file_id
en tu base de datos.
Procesa por separado resultados correctos y errores.
Reintenta solo requests fallidas.
Utiliza Batch únicamente cuando el usuario no necesita una respuesta inmediata.
Cuándo conviene usar Batch API
Trabajo offline
Miles de tareas que pueden esperar varias horas.
Procesamiento nocturno
Jobs recurrentes que no bloquean al usuario.
Grandes migraciones
Clasificación, embeddings o transformación de datasets.
Cuándo no deberías utilizar Batch API
Conversaciones en vivo
El usuario espera una respuesta en segundos.
Procesamiento interactivo
Una aplicación necesita reaccionar inmediatamente.
Tareas encadenadas inmediatas
El siguiente paso depende del resultado de la request actual.
Buenas prácticas de seguridad con Batch API
No incluyas secretos innecesarios en el JSONL.
Valida los datos antes de generar el batch.
Controla quién puede crear trabajos masivos.
Guarda logs de creación y resultados.
Valida outputs antes de escribirlos automáticamente en sistemas críticos.
Documentación oficial de Batch API OpenAI
Los endpoints, modelos, precios y límites pueden evolucionar.
Batch API
Comprueba creación de batches, archivos JSONL, estados, output files, límites y pricing vigente.
Consultar documentación oficial →Guías relacionadas con Batch API OpenAI
Continúa aprendiendo a optimizar costos, rendimiento y escala.
FAQ sobre Batch API OpenAI
Respuestas sobre JSONL, precios, duración, errores y resultados.
Batch API OpenAI permite procesar grandes conjuntos de solicitudes de forma asíncrona mediante archivos JSONL.
La ventana de procesamiento soportada actualmente es de hasta 24 horas, aunque el batch puede completarse antes.
Sí. En los modelos compatibles, Batch se factura actualmente al 50% de la tarifa Standard.
Los archivos de entrada deben utilizar formato JSONL, con una solicitud por línea.
OpenAI permite actualmente archivos Batch JSONL de hasta 200 MB.
Sí.
/v1/responses
está entre
los endpoints
actualmente admitidos
por Batch API.
Es un identificador asignado por tu aplicación para relacionar una request del archivo de entrada con su resultado.
Es el ID del archivo que contiene los resultados correctamente procesados del batch.
Es el ID del archivo que contiene resultados correspondientes a solicitudes que produjeron errores.
No es su uso ideal. Batch API está diseñada para trabajos asíncronos que pueden esperar, no para conversaciones interactivas.
Continúa con Background Mode en OpenAI API
Ya sabes cómo procesar miles de solicitudes de forma asíncrona. El siguiente paso es aprender cómo ejecutar una respuesta individual larga en segundo plano mediante Responses API.
Ver Background Mode →