• Necesitas procesar grandes volúmenes de datos
• No se requieren respuestas inmediatas
• Quieres optimizar para eficiencia de costos
• Estás ejecutando evaluaciones o análisis a gran escala

​

API de Lotes de Mensajes

​

Cómo funciona la API de Lotes de Mensajes

1. El sistema crea un nuevo Lote de Mensajes con las solicitudes de Mensajes proporcionadas.
2. El lote se procesa luego asincrónicamente, con cada solicitud manejada independientemente.
3. Puedes consultar el estado del lote y recuperar resultados cuando el procesamiento haya terminado para todas las solicitudes.

• Evaluaciones a gran escala: Procesar miles de casos de prueba de manera eficiente.
• Moderación de contenido: Analizar grandes volúmenes de contenido generado por usuarios asincrónicamente.
• Análisis de datos: Generar insights o resúmenes para grandes conjuntos de datos.
• Generación masiva de contenido: Crear grandes cantidades de texto para varios propósitos (ej., descripciones de productos, resúmenes de artículos).

​

Limitaciones de lotes

• Un Lote de Mensajes está limitado a 100,000 solicitudes de Mensajes o 256 MB de tamaño, lo que se alcance primero.
• Procesamos cada lote tan rápido como sea posible, con la mayoría de los lotes completándose dentro de 1 hora. Podrás acceder a los resultados del lote cuando todos los mensajes 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 por 29 días después de la creación. Después de eso, aún puedes ver el Lote, pero sus resultados ya no estarán disponibles para descarga.
• Los lotes están limitados a un Espacio de Trabajo. Puedes ver todos los lotes—y sus resultados—que fueron creados dentro del Espacio de Trabajo al que pertenece tu clave API.
• Los límites de tasa se aplican tanto a las solicitudes HTTP de la API de Lotes como al número de solicitudes dentro de un lote esperando ser procesadas. Ver límites de tasa de la API de Lotes de Mensajes. Adicionalmente, podemos ralentizar el procesamiento basado en 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 Espacio de Trabajo.

​

Modelos soportados

• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
• Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 y claude-3-5-sonnet-20241022)
• Claude Haiku 3.5 (claude-3-5-haiku-20241022)
• Claude Haiku 3 (claude-3-haiku-20240307)
• Claude Opus 3 (claude-3-opus-20240229)

​

Qué se puede procesar por lotes

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

​

Precios

​

Cómo usar la API de Lotes de Mensajes

​

Prepara y crea tu lote

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

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-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

{
  "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

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'

​

Recuperando resultados del lote

#!/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

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-20250514","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-20250514","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}}}}

​

Usando caché de prompts con Lotes de Mensajes

1. Incluye bloques cache_control idénticos en cada solicitud de Mensaje dentro de tu lote
2. Mantén un flujo constante de solicitudes para prevenir que las entradas de caché expiren después de su tiempo de vida de 5 minutos
3. Estructura tus solicitudes para compartir tanto contenido en caché como sea posible

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-20250514",
                "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-20250514",
                "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."}
                ]
            }
        }
    ]
}'

​

Mejores prácticas para procesamiento por lotes efectivo

• Monitorea el estado de procesamiento del lote regularmente e implementa lógica de reintento apropiada para solicitudes fallidas.
• Usa valores custom_id significativos para hacer coincidir fácilmente resultados con solicitudes, ya que el orden no está garantizado.
• Considera dividir conjuntos de datos muy grandes en múltiples lotes para mejor manejabilidad.
• Ejecuta una prueba seca de una sola forma de solicitud con la API de Mensajes para evitar errores de validación.

​

Solucionando problemas comunes

• Verifica que el tamaño total de la solicitud del lote no exceda 256 MB. Si el tamaño de la solicitud es demasiado grande, puedes obtener un error 413 request_too_large.
• Verifica que estés usando modelos soportados para todas las solicitudes en el lote.
• Asegúrate de que cada solicitud en el lote tenga un custom_id único.
• Asegúrate de que hayan pasado menos de 29 días desde el tiempo created_at del lote (no el tiempo ended_at de procesamiento). Si han pasado más de 29 días, los resultados ya no serán visibles.
• Confirma que el lote no haya sido cancelado.

​

Almacenamiento y privacidad de lotes

• Aislamiento de espacio de trabajo: Los lotes están aislados 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 del lote están disponibles por 29 días después de que se crea el lote, permitiendo tiempo amplio para recuperación y procesamiento.

​

FAQ