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 asíncrono. Este patrón es particularmente útil cuando:
  • 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
La API de Lotes de Mensajes es nuestra primera implementación de este patrón.

​
API de Lotes de Mensajes

La API de Lotes de Mensajes es una forma poderosa y rentable de procesar asincrónicamente grandes volúmenes de solicitudes de Mensajes. Este enfoque es adecuado para tareas que no requieren respuestas inmediatas, con la mayoría de los lotes terminando en menos de 1 hora mientras reduce los costos en un 50% y aumenta el rendimiento. Puedes explorar la referencia de la API directamente, además de esta guía.

​
Cómo funciona la API de Lotes de Mensajes

Cuando envías una solicitud a 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.
Esto es especialmente útil para operaciones masivas que no requieren resultados inmediatos, tales como:
  • Evaluaciones a gran escala: Procesar miles de casos de prueba eficientemente.
  • 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 Mensaje 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

Todos los modelos activos soportan la API de Lotes de Mensajes.

​
Qué se puede procesar por lotes

Cualquier solicitud que puedas hacer a la API de Mensajes puede incluirse en un lote. Esto incluye:
  • Visión
  • Uso de herramientas
  • Mensajes del sistema
  • Conversaciones de múltiples turnos
  • Cualquier característica beta
Dado que cada solicitud en el lote se procesa independientemente, puedes mezclar diferentes tipos de solicitudes dentro de un solo lote.
Dado que los lotes pueden tomar más de 5 minutos para procesar, considera usar la duración de caché de 1 hora con el almacenamiento en caché de prompts para mejores tasas de acierto de caché al procesar lotes con contexto compartido.

​
Precios

La API de Lotes ofrece ahorros significativos de costos. Todo el uso se cobra al 50% de los precios estándar de la API.
ModelBatch inputBatch output
Claude Opus 4.1$7.50 / MTok$37.50 / MTok
Claude Opus 4$7.50 / MTok$37.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

​
Cómo usar la API de Lotes de Mensajes

​
Prepara y crea tu lote

Un Lote de Mensajes está compuesto por una lista de solicitudes para crear un Mensaje. La forma de una solicitud individual comprende:
  • Un custom_id único para identificar la solicitud de Mensajes
  • Un objeto params con los parámetros estándar de la API de Mensajes
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": "Hola, mundo"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hola de nuevo, amigo"}
                ]
            }
        }
    ]
}'
En este ejemplo, dos solicitudes separadas se agrupan en lotes para procesamiento asíncrono. 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 MensajesLa validación del objeto params para cada solicitud de mensaje se realiza asincrónicamente, y los errores de validación se devuelven cuando el procesamiento de todo el lote ha terminado. Puedes asegurar que estás construyendo tu entrada correctamente verificando la forma de tu solicitud con la API de Mensajes primero.
Cuando un lote se crea por primera vez, la respuesta tendrá un estado de procesamiento de in_progress.
JSON
{
  "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 Lote de Mensajes indica la etapa de procesamiento en la que se encuentra el 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 endpoint de recuperación: 
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":"([^"]+)".*/El estado de procesamiento del lote \1 es \2/'
Puedes consultar este endpoint para saber cuándo el procesamiento ha terminado.

​
Recuperando resultados del lote

Una vez que el procesamiento del lote ha terminado, cada solicitud de Mensajes en el lote tendrá un resultado. Hay 4 tipos de resultado:
Tipo de ResultadoDescripción
succeededLa solicitud fue exitosa. Incluye el resultado del mensaje.
erroredLa solicitud encontró un error y no se creó un mensaje. Los posibles errores incluyen solicitudes inválidas y errores internos del servidor. No se te cobrará por estas solicitudes.
canceledEl usuario canceló el lote antes de que esta solicitud pudiera ser enviada al modelo. No se te cobrará por estas solicitudes.
expiredEl lote alcanzó su expiración de 24 horas antes de que esta solicitud pudiera ser enviada al modelo. No se te cobrará por estas solicitudes.
Verás un resumen 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 descarga en la propiedad results_url del Lote de Mensajes, 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 de vuelta en lugar de descargarlos todos de una 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 "¡Éxito! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # El cuerpo de la solicitud debe ser corregido antes de reenviar la solicitud
            echo "Error de validación: $custom_id"
          else
            # La solicitud puede ser reintentada directamente
            echo "Error del servidor: $custom_id"
          fi
          ;;
        "expired")
          echo "Expirado: $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 sola solicitud en el Lote de Mensajes. Para cada resultado transmitido, puedes hacer algo diferente dependiendo de su custom_id y tipo de resultado. Aquí hay un ejemplo de conjunto de resultados:
.jsonl file
{"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":"¡Hola de nuevo! Es agradable verte. ¿Cómo puedo ayudarte hoy? ¿Hay algo específico de lo que te gustaría charlar o alguna pregunta que tengas?"}],"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":"¡Hola! ¿Cómo puedo ayudarte hoy? Siéntete libre de hacerme cualquier pregunta o hazme saber si hay algo de lo que te gustaría charlar."}],"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á a nuestra forma de error estándar.
Los resultados del lote pueden no coincidir con el orden de entradaLos 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 para la segunda solicitud del lote se devuelve antes que la primera. Para hacer coincidir correctamente los resultados con sus solicitudes correspondientes, siempre usa el campo custom_id.

​
Usando almacenamiento en caché de prompts con Lotes de Mensajes

La API de Lotes de Mensajes soporta el almacenamiento en caché de prompts, permitiéndote potencialmente reducir costos y tiempo de procesamiento para solicitudes de lote. Los descuentos de precios del almacenamiento en caché de prompts y Lotes de Mensajes pueden acumularse, proporcionando ahorros de costos aún mayores cuando ambas características se usan juntas. Sin embargo, dado que las solicitudes de lote se procesan asincrónicamente y concurrentemente, 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 tus solicitudes de lote:
  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
Ejemplo de implementar almacenamiento en caché de prompts 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": "Eres un asistente de IA encargado de analizar obras literarias. Tu objetivo es proporcionar comentarios perspicaces sobre temas, personajes y estilo de escritura.\n"
                    },
                    {
                        "type": "text",
                        "text": "<todo el contenido de Orgullo y Prejuicio>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analiza los temas principales en Orgullo y Prejuicio."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "Eres un asistente de IA encargado de analizar obras literarias. Tu objetivo es proporcionar comentarios perspicaces sobre temas, personajes y estilo de escritura.\n"
                    },
                    {
                        "type": "text",
                        "text": "<todo el contenido de Orgullo y Prejuicio>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Escribe un resumen de Orgullo y Prejuicio."}
                ]
            }
        }
    ]
}'
En este ejemplo, ambas solicitudes en el lote incluyen mensajes del sistema idénticos y el texto completo de Orgullo y Prejuicio marcado con cache_control para aumentar la probabilidad de aciertos de caché.

​
Mejores prácticas para lotes efectivos

Para obtener el máximo provecho de la API de Lotes:
  • 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 en seco de una sola forma de solicitud con la API de Mensajes para evitar errores de validación.

​
Solución de problemas comunes

Si experimentas comportamiento inesperado:
  • 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 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.
Nota que la falla de una solicitud en un lote no afecta el procesamiento de otras solicitudes.

​
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

Los lotes pueden tomar hasta 24 horas para procesarse, pero muchos terminarán antes. El tiempo real de procesamiento depende del tamaño del lote, la demanda actual y tu volumen de solicitudes. Es posible que un lote expire y no se complete dentro de 24 horas.
Ver arriba para la lista de modelos soportados.
Sí, la API de Lotes de Mensajes soporta todas las características disponibles en la API de Mensajes, incluyendo características beta. Sin embargo, la transmisión no está soportada para solicitudes de lote.
La API de Lotes de Mensajes ofrece un descuento del 50% en todo el uso comparado con los precios estándar de la API. Esto se aplica a tokens de entrada, tokens de salida y cualquier token especial. Para más sobre precios, visita nuestra página de precios.
No, una vez que un lote ha sido enviado, no puede ser modificado. Si necesitas hacer cambios, debes cancelar el lote actual y enviar uno nuevo. Nota que la cancelación puede no tomar efecto inmediato.
La API de Lotes de Mensajes tiene límites de tasa basados en solicitudes HTTP además de límites en el número de solicitudes que necesitan procesamiento. Ver límites de tasa de la API de Lotes de Mensajes. El uso de la API de Lotes no afecta los límites de tasa en la API de Mensajes.
Cuando recuperes los resultados, cada solicitud tendrá un campo result indicando si succeeded, errored, fue canceled, o expired. Para resultados errored, se proporcionará información adicional del error. Ve el objeto de respuesta de error en la referencia de la API.
La API de Lotes de Mensajes está diseñada con medidas fuertes de privacidad y separación de datos:
  1. Los lotes y sus resultados están aislados dentro del Espacio de Trabajo en el que fueron creados. Esto significa que solo pueden ser accedidos por claves API de ese mismo Espacio de Trabajo.
  2. Cada solicitud dentro de un lote se procesa independientemente, sin filtración de datos entre solicitudes.
  3. Los resultados solo están disponibles por un tiempo limitado (29 días), y siguen nuestra política de retención de datos.
  4. La descarga de resultados de lote en la Consola puede ser deshabilitada a nivel de organización o por espacio de trabajo.
Sí, es posible usar almacenamiento en caché de prompts con la API de Lotes de Mensajes. Sin embargo, debido a que las solicitudes de lote asíncronas pueden ser procesadas concurrentemente y en cualquier orden, los aciertos de caché se proporcionan en base al mejor esfuerzo.