Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
El procesamiento por lotes es un enfoque poderoso para manejar grandes volúmenes de solicitudes de manera eficiente. En lugar de procesar solicitudes una a la vez con respuestas inmediatas, el procesamiento por lotes te permite enviar múltiples solicitudes juntas para procesamiento asincrónico. Este patrón es particularmente útil cuando:
La API de lotes de mensajes es la primera implementación de este patrón por parte de Anthropic.
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
La API de lotes de mensajes es una forma poderosa y rentable de procesar de forma asincrónica grandes volúmenes de solicitudes de Mensajes. Este enfoque es muy adecuado para tareas que no requieren respuestas inmediatas, con la mayoría de los lotes finalizando en menos de 1 hora mientras se reducen costos en un 50% y se aumenta el rendimiento.
Puedes explorar la referencia de la API directamente, además de esta guía.
Was this page helpful?
Cuando envías una solicitud a la API de lotes de mensajes:
Esto es especialmente útil para operaciones en masa que no requieren resultados inmediatos, como:
Todos los modelos activos son compatibles con la API de lotes de mensajes.
Cualquier solicitud que puedas hacer a la API de mensajes puede incluirse en un lote. Esto incluye:
Dado que cada solicitud en el lote se procesa independientemente, puedes mezclar diferentes tipos de solicitudes dentro de un único lote.
Dado que los lotes pueden tardar más de 5 minutos en procesarse, considera usar la duración de caché de 1 hora con almacenamiento en caché de indicaciones para mejores tasas de acierto de caché al procesar lotes con contexto compartido.
La API de lotes ofrece ahorros de costos significativos. Todo el uso se cobra al 50% de los precios estándar de la API.
| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Un lote de mensajes se compone de una lista de solicitudes para crear un mensaje. La forma de una solicitud individual consta de:
custom_id único para identificar la solicitud de mensajesparams con los parámetros estándar de la API de mensajesPuedes crear un lote pasando esta lista al parámetro requests:
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'En este ejemplo, dos solicitudes separadas se procesan por lotes juntas para procesamiento asincrónico. Cada solicitud tiene un custom_id único y contiene los parámetros estándar que usarías para una llamada a la API de mensajes.
Prueba tus solicitudes de lote con la API de mensajes
La validación del objeto params para cada solicitud de mensaje se realiza de forma asincrónica, y los errores de validación se devuelven cuando el procesamiento de todo el lote ha finalizado. Puedes asegurar que estás construyendo tu entrada correctamente verificando la forma de tu solicitud con la API de mensajes primero.
Cuando se crea un lote por primera vez, la respuesta tendrá un estado de procesamiento de in_progress.
{
"id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": null,
"results_url": null
}El campo processing_status del lote de mensajes indica la etapa en la que se encuentra el procesamiento del lote. Comienza como in_progress, luego se actualiza a ended una vez que todas las solicitudes en el lote han terminado de procesarse, y los resultados están listos. Puedes monitorear el estado de tu lote visitando la Consola, o usando el punto final de recuperación.
Para consultar un lote de mensajes, necesitarás su id, que se proporciona en la respuesta al crear un lote o listando lotes. Puedes implementar un bucle de consulta que verifique el estado del lote periódicamente hasta que el procesamiento haya finalizado:
#!/bin/sh
until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
| grep -o '"processing_status":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4) == "ended" ]]; do
echo "Batch $MESSAGE_BATCH_ID is still processing..."
sleep 60
done
echo "Batch $MESSAGE_BATCH_ID has finished processing"Puedes listar todos los lotes de mensajes en tu espacio de trabajo usando el punto final de lista. La API admite paginación, obteniendo automáticamente páginas adicionales según sea necesario:
#!/bin/sh
if ! command -v jq &> /dev/null; then
echo "Error: This script requires jq. Please install it first."
exit 1
fi
BASE_URL="https://api.anthropic.com/v1/messages/batches"
has_more=true
after_id=""
while [ "$has_more" = true ]; do
# Construct URL with after_id if it exists
if [ -n "$after_id" ]; then
url="${BASE_URL}?limit=20&after_id=${after_id}"
else
url="$BASE_URL?limit=20"
fi
response=$(curl -s "$url" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01")
# Extract values using jq
has_more=$(echo "$response" | jq -r '.has_more')
after_id=$(echo "$response" | jq -r '.last_id')
# Process and print each entry in the data array
echo "$response" | jq -c '.data[]' | while read -r entry; do
echo "$entry" | jq '.'
done
doneUna vez que el procesamiento de lotes ha finalizado, cada solicitud de Messages en el lote tiene un resultado. Hay 4 tipos de resultados:
| Tipo de Resultado | Descripción |
|---|---|
succeeded | La solicitud fue exitosa. Incluye el resultado del mensaje. |
errored | La solicitud encontró un error y no se creó un mensaje. Los errores posibles incluyen solicitudes inválidas y errores internos del servidor. No se le cobrará por estas solicitudes. |
canceled | El usuario canceló el lote antes de que esta solicitud pudiera enviarse al modelo. No se le cobrará por estas solicitudes. |
expired | El lote alcanzó su vencimiento de 24 horas antes de que esta solicitud pudiera enviarse al modelo. No se le cobrará por estas solicitudes. |
Verá una descripción general de sus resultados con request_counts del lote, que muestra cuántas solicitudes alcanzaron cada uno de estos cuatro estados.
Los resultados del lote están disponibles para descargar en la propiedad results_url en el Message Batch, y si los permisos de la organización lo permiten, en la Console. Debido al tamaño potencialmente grande de los resultados, se recomienda transmitir resultados en lugar de descargarlos todos a la vez.
#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| grep -o '"results_url":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4 \
| while read -r url; do
curl -s "$url" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| sed 's/}{/}\n{/g' \
| while IFS= read -r line
do
result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
case "$result_type" in
"succeeded")
echo "Success! $custom_id"
;;
"errored")
if [ "$error_type" = "invalid_request_error" ]; then
# Request body must be fixed before re-sending request
echo "Validation error: $custom_id"
else
# Request can be retried directly
echo "Server error: $custom_id"
fi
;;
"expired")
echo "Expired: $line"
;;
esac
done
done
Los resultados están en formato .jsonl, donde cada línea es un objeto JSON válido que representa el resultado de una única solicitud en el Message Batch. Para cada resultado transmitido, puede hacer algo diferente dependiendo de su custom_id y tipo de resultado. Aquí hay un conjunto de resultados de ejemplo:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}Si su resultado tiene un error, su result.error se establecerá en la forma de error estándar.
Los resultados del lote pueden no coincidir con el orden de entrada
Los resultados del lote pueden devolverse en cualquier orden y pueden no coincidir con el orden de las solicitudes cuando se creó el lote. En el ejemplo anterior, el resultado de la segunda solicitud del lote se devuelve antes que la primera. Para hacer coincidir correctamente los resultados con sus solicitudes correspondientes, siempre use el campo custom_id.
Puede cancelar un Message Batch que se está procesando actualmente usando el punto final de cancelación. Inmediatamente después de la cancelación, el processing_status de un lote será canceling. Puede usar la misma técnica de sondeo descrita anteriormente para esperar hasta que se finalice la cancelación. Los lotes cancelados terminan con un estado de ended y pueden contener resultados parciales para solicitudes que se procesaron antes de la cancelación.
#!/bin/sh
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"La respuesta mostrará el lote en estado canceling:
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "canceling",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
"results_url": null
}La API de Message Batches admite el almacenamiento en caché de indicaciones, lo que le permite reducir potencialmente los costos y el tiempo de procesamiento para solicitudes por lotes. Los descuentos de precios del almacenamiento en caché de indicaciones y Message Batches se pueden acumular, proporcionando ahorros de costos aún mayores cuando se utilizan ambas características juntas. Sin embargo, dado que las solicitudes por lotes se procesan de forma asincrónica y concurrente, los aciertos de caché se proporcionan en base al mejor esfuerzo. Los usuarios típicamente experimentan tasas de acierto de caché que van del 30% al 98%, dependiendo de sus patrones de tráfico.
Para maximizar la probabilidad de aciertos de caché en sus solicitudes por lotes:
cache_control idénticos en cada solicitud de Message dentro de su loteEjemplo de implementación del almacenamiento en caché de indicaciones en un lote:
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Write a summary of Pride and Prejudice."}
]
}
}
]
}'En este ejemplo, ambas solicitudes en el lote incluyen mensajes del sistema idénticos y el texto completo de Pride and Prejudice marcado con cache_control para aumentar la probabilidad de aciertos de caché.
El encabezado beta output-300k-2026-03-24 eleva el límite de max_tokens a 300.000 para solicitudes por lotes usando Claude Opus 4.6 o Claude Sonnet 4.6. Incluya el encabezado para generar salidas mucho más largas que el límite estándar (64k a 128k dependiendo del modelo) en un solo turno.
La salida extendida está disponible solo en la API de Message Batches, no en la API de Messages sincrónica. Es compatible con la API de Claude y no está disponible en Amazon Bedrock, Vertex AI o Microsoft Foundry.
Utilice la salida extendida para generación de formato largo, como borradores de libros completos y documentación técnica, extracción de datos estructurados exhaustiva, andamios de generación de código grande y cadenas de razonamiento largo.
Una generación de 300k tokens puede tomar más de una hora en completarse, así que planifique sus envíos de lotes teniendo en cuenta la ventana de procesamiento de 24 horas. Se aplica la fijación de precios estándar de lotes (50% de los precios estándar de la API).
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: output-300k-2026-03-24" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "long-form-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 300000,
"messages": [
{"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
]
}
}
]
}'Para aprovechar al máximo la API de Batches:
custom_id significativos para hacer coincidir fácilmente los resultados con las solicitudes, ya que el orden no está garantizado.Si experimenta un comportamiento inesperado:
request_too_large.custom_id único.created_at del lote (no el tiempo de ended_at del procesamiento). Si han pasado más de 29 días, los resultados ya no serán visibles.Tenga en cuenta que el fallo de una solicitud en un lote no afecta el procesamiento de otras solicitudes.
Aislamiento del espacio de trabajo: Los lotes se aíslan dentro del espacio de trabajo en el que se crean. Solo pueden ser accedidos por claves API asociadas con ese espacio de trabajo, o usuarios con permiso para ver lotes del espacio de trabajo en la Consola.
Disponibilidad de resultados: Los resultados de los lotes están disponibles durante 29 días después de que se crea el lote, lo que permite tiempo suficiente para la recuperación y el procesamiento.
El procesamiento por lotes almacena datos de solicitud y respuesta hasta 29 días después de la creación del lote. Puede eliminar un lote de mensajes en cualquier momento después del procesamiento utilizando el punto final DELETE /v1/messages/batches/{batch_id}. Para eliminar un lote en progreso, cancélelo primero. El procesamiento asincrónico requiere almacenamiento del lado del servidor de entradas y salidas hasta la finalización del lote y la recuperación de resultados.
Para elegibilidad de ZDR en todas las características, consulte Retención de API y datos.