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:

• Necesitas procesar grandes volúmenes de datos
• Las respuestas inmediatas no son necesarias
• Deseas optimizar la eficiencia de costos
• Estás ejecutando evaluaciones o análisis a gran escala

La API de Message Batches es nuestra primera implementación de este patrón.

API de Message Batches

La API de Message Batches es una forma poderosa y rentable de procesar de forma asincrónica grandes volúmenes de solicitudes de Messages. Este enfoque es muy adecuado para tareas que no requieren respuestas inmediatas, con la mayoría de lotes finalizándose en menos de 1 hora mientras se reducen costos en un 50% y se aumenta el rendimiento.

Puedes explorar la referencia de API directamente, además de esta guía.

Cómo funciona la API de Message Batches

Cuando envías una solicitud a la API de Message Batches:

1. El sistema crea un nuevo Message Batch con las solicitudes de Messages proporcionadas.
2. El lote se procesa entonces de forma asincrónica, con cada solicitud manejada independientemente.
3. Puedes sondear el estado del lote y recuperar resultados cuando el procesamiento haya finalizado para todas las solicitudes.

Esto es especialmente útil para operaciones en masa que no requieren resultados inmediatos, tales como:

• Evaluaciones a gran escala: Procesa miles de casos de prueba de manera eficiente.
• Moderación de contenido: Analiza grandes volúmenes de contenido generado por usuarios de forma asincrónica.
• Análisis de datos: Genera información o resúmenes para grandes conjuntos de datos.
• Generación de contenido en masa: Crea grandes cantidades de texto para varios propósitos (por ejemplo, descripciones de productos, resúmenes de artículos).

Limitaciones de lotes

• Un Message Batch está limitado a 100,000 solicitudes de Message o 256 MB de tamaño, lo que se alcance primero.
• Procesamos cada lote lo más rápido posible, con la mayoría de lotes completándose dentro de 1 hora. Podrás acceder a los resultados del lote cuando todos los mensajes se hayan completado o después de 24 horas, lo que ocurra primero. Los lotes expirarán si el procesamiento no se completa dentro de 24 horas.
• Los resultados del lote están disponibles durante 29 días después de la creación. Después de eso, aún puedes ver el Batch, pero sus resultados ya no estarán disponibles para descargar.
• Los lotes están limitados a un Workspace. Puedes ver todos los lotes—y sus resultados—que fueron creados dentro del Workspace al que pertenece tu clave de API.
• Los límites de velocidad se aplican tanto a las solicitudes HTTP de la API de Batches como al número de solicitudes dentro de un lote esperando ser procesadas. Consulta Límites de velocidad de la API de Message Batches. Además, podemos ralentizar el procesamiento según la demanda actual y tu volumen de solicitudes. En ese caso, puedes ver más solicitudes expirando después de 24 horas.
• Debido al alto rendimiento y procesamiento concurrente, los lotes pueden exceder ligeramente el límite de gasto configurado de tu Workspace.

Modelos soportados

Todos los modelos activos soportan la API de Message Batches.

Qué se puede procesar por lotes

Cualquier solicitud que puedas hacer a la API de Messages puede incluirse en un lote. Esto incluye:

• Visión
• Uso de herramientas
• Mensajes del sistema
• Conversaciones de múltiples turnos
• Cualquier característica beta

Como cada solicitud en el lote se procesa independientemente, puedes mezclar diferentes tipos de solicitudes dentro de un único lote.

Precios

La API de Batches ofrece ahorros de costos significativos. Todo el uso se cobra al 50% de los precios estándar de la API.

Cómo usar la API de Message Batches

Prepara y crea tu lote

Un Message Batch se compone de una lista de solicitudes para crear un Message. La forma de una solicitud individual se compone de:

• Un custom_id único para identificar la solicitud de Messages
• Un objeto params con los parámetros estándar de Messages API

Puedes 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-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "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 Messages.

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
}

Rastreando tu lote

El campo processing_status del Message Batch 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 finalizado el procesamiento y los resultados están listos. Puedes monitorear el estado de tu lote visitando la Consola, o usando el endpoint de recuperación.

Sondeo para la finalización de Message Batch

Para sondear un Message Batch, necesitarás su id, que se proporciona en la respuesta al crear un lote o listando lotes. Puedes implementar un bucle de sondeo que verifique el estado del lote periódicamente hasta que el procesamiento haya finalizado:

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(
        MESSAGE_BATCH_ID
    )
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

Listando todos los Message Batches

Puedes listar todos los Message Batches en tu Workspace usando el endpoint de lista. La API soporta paginación, obteniendo automáticamente páginas adicionales según sea necesario:

import anthropic

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(
    limit=20
):
    print(message_batch)

Recuperando resultados del lote

Una vez que el procesamiento del lote ha finalizado, cada solicitud de Messages en el lote tendrá un resultado. Hay 4 tipos de resultados:

Verás una descripción general de tus resultados con el 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 el permiso de la organización lo permite, en la Consola. 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" ]; 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 estará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, puedes 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-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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 tu resultado tiene un error, su result.error se establecerá en nuestra forma de error estándar.

Cancelando un Message Batch

Puedes cancelar un Message Batch que está siendo procesado actualmente usando el endpoint de cancelación. Inmediatamente después de la cancelación, el processing_status de un lote será canceling. Puedes usar la misma técnica de sondeo descrita anteriormente para esperar hasta que la cancelación se finalice. Los lotes cancelados terminan con un estado de ended y pueden contener resultados parciales para solicitudes que fueron procesadas antes de la cancelación.

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

La respuesta mostrará el lote en un 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
}

Uso del almacenamiento en caché de indicaciones con Message Batches

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:

1. Incluya bloques cache_control idénticos en cada solicitud de Message dentro de su lote
2. Mantenga un flujo constante de solicitudes para evitar que las entradas de caché expiren después de su vida útil de 5 minutos
3. Estructure sus solicitudes para compartir la mayor cantidad posible de contenido almacenado en caché

Ejemplo 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-sonnet-4-5",
                "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-sonnet-4-5",
                "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é.

Mejores prácticas para procesamiento por lotes efectivo

Para aprovechar al máximo la API de Batches:

• Monitoree regularmente el estado del procesamiento por lotes e implemente la lógica de reintentos apropiada para solicitudes fallidas.
• Utilice valores custom_id significativos para hacer coincidir fácilmente los resultados con las solicitudes, ya que el orden no está garantizado.
• Considere dividir conjuntos de datos muy grandes en múltiples lotes para una mejor manejabilidad.
• Realice una prueba de ejecución de una única forma de solicitud con la API de Messages para evitar errores de validación.

Solución de problemas comunes

Si experimenta un comportamiento inesperado:

• Verifique que el tamaño total de la solicitud por lotes no exceda 256 MB. Si el tamaño de la solicitud es demasiado grande, puede obtener un error 413 request_too_large.
• Compruebe que está utilizando modelos compatibles para todas las solicitudes en el lote.
• Asegúrese de que cada solicitud en el lote tenga un custom_id único.
• Asegúrese de que hayan pasado menos de 29 días desde el tiempo de created_at del lote (no el tiempo de procesamiento ended_at). Si han pasado más de 29 días, los resultados ya no serán visibles.
• Confirme que el lote no ha sido cancelado.

Tenga en cuenta que el fallo de una solicitud en un lote no afecta el procesamiento de otras solicitudes.

Almacenamiento y privacidad de lotes

• Aislamiento del Workspace: Los lotes se aíslan dentro del Workspace en el que se crean. Solo pueden ser accedidos por claves API asociadas con ese Workspace, o por usuarios con permiso para ver lotes de Workspace 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.

Preguntas frecuentes