Respuesta rápida: La Claude Batch API procesa solicitudes de la Messages API de forma asíncrona con un 50 % de descuento tanto en tokens de entrada como de salida. Envías hasta 100.000 solicitudes (o 256 MB) en una sola llamada, haces sondeos hasta que el lote termina y luego lees los resultados indexados por tu propio custom_id. La mayoría de los lotes terminan en menos de una hora, y el límite máximo es de 24 horas.
Tienes 40.000 tickets de soporte que clasificar, o un catálogo de productos que reescribir, o un mes de transcripciones que resumir. Nada de eso es urgente. Aun así, cada una de esas llamadas se factura a precio completo cuando las lanzas una a una, y te pasas la tarde vigilando reintentos contra tu límite de tasa.
La Claude Batch API existe exactamente para este tipo de trabajo. Le entregas a Anthropic una lista de solicitudes, te alejas y vuelves a un archivo de resultados que costó la mitad de lo que habrían costado las mismas llamadas de forma síncrona. Sin cola que ejecutar, sin ajuste de concurrencia, sin lógica de retroceso.
Esta guía cubre qué hace el endpoint de lotes, cuánto cuesta, cómo enviar y recoger un trabajo, y cómo hacer que tu agente de codificación pruebe todo el flujo con Apidog CLI antes de apuntarlo a datos reales.
¿Qué es la Claude Batch API?
La Claude Batch API es un endpoint asíncrono en /v1/messages/batches que acepta muchas solicitudes de la Messages API en un único envío y devuelve sus resultados cuando finaliza el procesamiento. Cambia latencia por un descuento del 50 %. Anthropic la documenta en procesamiento por lotes.
Las restricciones que debes tener en cuenta al diseñar:
- Tamaño: hasta 100.000 solicitudes o 256 MB por lote, lo que alcances primero.
- Tiempos: la mayoría de los lotes se completan en una hora; 24 horas es el máximo antes de que las solicitudes sin terminar expiren.
- Retención: los resultados permanecen disponibles durante 29 días después de crear el lote.
- Paridad de funciones: visión, uso de herramientas, prompts de sistema y caché de prompts funcionan dentro de un lote.
- Orden: los resultados vuelven en cualquier orden, así que los indexas por
custom_idy nunca por posición.
Ese último punto es el que pilla a la gente. Un lote es una bolsa, no una cola.
Cuánto cuesta la Claude Batch API
El descuento es un 50 % plano tanto en tokens de entrada como de salida, aplicado a cualquier modelo que nombre cada solicitud. Puedes mezclar modelos dentro de un mismo lote, así que un clasificador barato y un resumidor caro pueden ir juntos.
| Modelo | Entrada / salida estándar por MTok | Entrada / salida por lotes por MTok |
|---|---|---|
| Claude Opus 5.5 | $4.00 / $20.00 | $2.00 / $10.00 |
| Claude Sonnet 5.5 | $2.00 / $10.00 | $1.00 / $5.00 |
| Claude Haiku 5.5 (prompts de hasta 100K) | $0.10 / $0.50 | $0.05 / $0.25 |
| Claude Haiku 5.5 (prompts de más de 100K) | $0.50 / $2.50 | $0.25 / $1.25 |
Lee con atención las filas de Haiku. Haiku 5.5 se factura según el tamaño del prompt, así que un prompt que supere los 100.000 tokens se factura a 5 veces la tarifa de prompt corto, con descuento por lotes o sin él. Calcula el trabajo de Haiku con contexto largo a $0.25 / $1.25, no a $0.05 / $0.25. Consulta la página de precios de Anthropic antes de construir una previsión sobre estos números, y lee nuestro desglose de a dónde va el gasto de la Claude API si la factura es la razón por la que estás aquí.
El precio por lotes también se combina con la caché de prompts, que es donde están los ahorros reales. Más sobre eso a continuación.
Envía tu primer lote
Instala el SDK oficial de Python y construye una lista de solicitudes. Cada una lleva un custom_id que eliges tú y un objeto params que se ve exactamente igual que una llamada normal a messages.create().
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
tickets = [
"Card declined three times, support chat timed out.",
"Love the new dashboard, the export button is hidden though.",
"Webhook stopped firing after the 2.4 upgrade.",
]
batch = client.messages.batches.create(
requests=[
Request(
custom_id=f"ticket-{i}",
params=MessageCreateParamsNonStreaming(
model="claude-haiku-5-5",
max_tokens=1024,
output_config={"effort": "low"},
messages=[{
"role": "user",
"content": f"Label this ticket billing, bug, or praise. One word.\n\n{text}",
}],
),
)
for i, text in enumerate(tickets)
]
)
print(batch.id, batch.processing_status)
Haz que custom_id tenga significado. Una clave primaria de base de datos o una ruta de archivo te ahorra una unión más adelante, y es lo único que vincula un resultado con su entrada.
Si prefieres HTTP en crudo, el mismo payload se envía a POST https://api.anthropic.com/v1/messages/batches con tus cabeceras x-api-key y anthropic-version. La referencia de creación de un lote de mensajes tiene el esquema completo.
Sondea el lote y recoge los resultados
Recupera el lote hasta que processing_status indique ended, y luego transmite los resultados. Cada resultado lleva el custom_id que estableciste y un result.type de succeeded, errored, canceled o expired.
import time
while True:
batch = client.messages.batches.retrieve(batch.id)
if batch.processing_status == "ended":
break
print("still working:", batch.request_counts.processing)
time.sleep(30)
labels, retry = {}, []
for result in client.messages.batches.results(batch.id):
if result.result.type == "succeeded":
msg = result.result.message
labels[result.custom_id] = next(b.text for b in msg.content if b.type == "text")
elif result.result.type == "errored":
retry.append(result.custom_id)
print(f"{len(labels)} labeled, {len(retry)} need another pass")
Dos modos de fallo merecen un manejo aparte. Un error invalid_request significa que el cuerpo de la solicitud era incorrecto, así que corrígelo antes de reenviarla. Cualquier otra cosa es del lado del servidor y es seguro reintentarla tal cual. Un resultado expired significa que la ventana de 24 horas se cerró antes de que se ejecutara esa solicitud, y esas también las reenvías.
Sondea con un temporizador de 30 a 60 segundos. Martillear el endpoint de recuperación cada segundo no te aporta nada y cuenta contra tus límites de tasa de la Claude API.
Combina el precio por lotes con la caché de prompts
La mayor ganancia viene de combinar los dos descuentos. Si cada solicitud de tu lote comparte un prefijo largo, una guía de estilo, una taxonomía, un contrato de 40 páginas, marca ese prefijo con cache_control y envía el mismo prefijo marcado en las 10.000 solicitudes.
shared_system = [
{"type": "text", "text": "You are a support triage analyst."},
{
"type": "text",
"text": taxonomy_document, # thousands of tokens, identical every time
"cache_control": {"type": "ephemeral"},
},
]
Pon ese bloque system en cada Request del lote. Cualquier solicitud cuyo prefijo coincida byte a byte con una entrada de caché viva factura ese prefijo a tarifas de lectura de caché, y el descuento del 50 % por lotes se aplica tanto a las lecturas como a las escrituras de caché. No calcules una tasa de aciertos perfecta: un lote procesa sus solicitudes de forma concurrente en lugar de en orden, así que los aciertos de caché dentro de un lote son lo mejor que se pueda. La guía de caché de prompts de Anthropic cubre las reglas del prefijo: cualquier byte que cambie antes de tu punto de corte invalida todo lo que viene después, así que deja las marcas de tiempo y el texto por elemento después del bloque en caché.
Deja que Claude Code pruebe el endpoint con Apidog CLI
Antes de gastar dinero en 100.000 solicitudes reales, querrás una prueba de regresión del ciclo de vida del lote: crear, recuperar, resultados. Escribir eso a mano en una GUI es lento. Deja que tu agente de codificación lo haga con Apidog CLI en su lugar.
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install # pick Claude Code when prompted
Luego un prompt a Claude Code:
In Apidog project 4820193, create a test case for POST https://api.anthropic.com/v1/messages/batches
that submits two Haiku 5.5 requests with custom_id ticket-0 and ticket-1, asserts the response
has an id and processing_status, then polls GET /v1/messages/batches/{id} until processing_status
is ended. Run it against the anthropic-staging environment and summarize failures.
El agente lee el esquema del payload, valida su propio JSON y luego crea y ejecuta el caso:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file batch-case.json
apidog test-case create --project 4820193 --file batch-case.json
apidog run --test-case 77214 --project 4820193 -e 992301 -r cli,json
Tu clave de API permanece en una variable de entorno de Apidog, así que nunca acaba en un prompt ni en un repositorio. Cambia el reporter a -r junit y el mismo comando se ejecuta en CI en cada fusión, que es la configuración de nuestra guía de pipelines con Apidog CLI. Si aún no has conectado la CLI a tu agente, empieza por usar Apidog CLI en Claude Code.
Cuándo el lote no es la opción correcta
| Carga de trabajo | ¿Usar lote? | Por qué |
|---|---|---|
| Resumen nocturno de los registros de ayer | Sí | Nadie está esperando; 50 % de descuento |
| Rellenar embeddings o etiquetas sobre un corpus | Sí | Encaja con el techo de 100.000 solicitudes |
| Ejecuciones de evaluación sobre un conjunto de prompts | Sí | Los resultados indexados por custom_id se asignan a IDs de prueba |
| Respuestas de la interfaz de chat | No | Los usuarios no esperarán una hora |
| Un bucle de agente que necesita la última respuesta para elegir el siguiente paso | No | Las solicitudes por lotes no pueden verse entre sí |
| Una solicitud que debe cumplir un SLA de 5 segundos | No | Sin garantía de latencia por debajo de 24 horas |
Algunas cosas tampoco se trasladan. El modo rápido no está disponible en la Batch API, los respaldos de rechazo del lado del servidor se rechazan ahí, y en Claude Opus 5.5 y Claude Sonnet 5.5 un tool_choice forzado de any o tool devuelve un 400 dentro de un lote exactamente igual que en una llamada normal. Usa tool_choice: auto con strict: true en su lugar.
Si gestionas infraestructura multiproveedor, el mismo patrón existe en otras partes: consulta la OpenAI Batch API y el modo por lotes de la Gemini API. Las formas difieren, la economía no.
Preguntas frecuentes
¿Qué es la Claude Batch API?
Es un endpoint asíncrono que ejecuta solicitudes estándar de la Messages API en bloque a un 50 % de los precios normales por token. Envías una lista de solicitudes con tus propios IDs, sondeas hasta que el lote termina y lees los resultados en un plazo de 29 días.
¿Cuánto cuesta la Claude Batch API?
La mitad de la tarifa estándar tanto en entrada como en salida. En Claude Sonnet 5.5 eso es $1.00 por millón de tokens de entrada y $5.00 por millón de tokens de salida, frente a $2.00 y $10.00 de forma síncrona.
¿Cuánto tarda un lote de Claude?
La mayoría de los lotes terminan en una hora. El máximo es de 24 horas, tras las cuales cualquier solicitud sin procesar devuelve un resultado expired y la reenvías.
¿Puedo usar la caché de prompts dentro de un lote?
Sí, y los descuentos se acumulan. Marca un prefijo compartido con cache_control, repite ese prefijo idéntico en cada solicitud, y las lecturas en caché se facturan a una fracción del precio de entrada además del descuento por lotes.
¿Qué ocurre cuando falla una solicitud en un lote?
Solo falla esa solicitud. Su resultado lleva type: "errored" con un objeto de error; todo lo demás sigue teniendo éxito. Los errores de validación necesitan un payload corregido, los errores del servidor son seguros de reintentar sin cambios.
¿Puedo cancelar un lote en ejecución?
Sí. client.messages.batches.cancel(batch_id) pasa el lote a canceling. Las solicitudes ya finalizadas conservan sus resultados; el resto vuelven como canceled.
¿La Batch API admite herramientas e imágenes?
Sí. Todas las funciones de la Messages API funcionan dentro de un lote, incluidas visión, definiciones de herramientas y prompts de sistema. Las excepciones son el modo rápido, los respaldos del lado del servidor y la elección forzada de herramienta en los modelos 5.5.
Conclusión
El procesamiento por lotes es el segundo mayor ahorro gratuito en la Claude API después de la caché de prompts, y no te cuesta nada en calidad: los mismos modelos, las mismas funciones, la mitad del precio, pagado en latencia que probablemente no estabas usando. Indexa tus resultados por custom_id, cachea el prefijo compartido y trata expired como un reintento en lugar de un fallo.
Prueba el ciclo de vida antes de escalarlo. Instala Apidog CLI, apunta tu agente de codificación a los endpoints de lotes y mantén el caso de prueba generado ejecutándose en CI para que un cambio de esquema nunca te sorprenda con 100.000 solicitudes. El plan gratuito cubre 4 usuarios, y puedes descargar Apidog y tener el primer caso en marcha en unos minutos.