Пакетная обработка — это мощный подход для эффективной обработки больших объёмов запросов. Вместо обработки запросов по одному с немедленными ответами, пакетная обработка позволяет отправлять несколько запросов вместе для асинхронной обработки. Этот подход особенно полезен в следующих случаях:

Необходимо обработать большие объёмы данных
Немедленные ответы не требуются
Вы хотите оптимизировать затраты
Вы проводите масштабные оценки или анализы

Message Batches API — это первая реализация данного подхода от Anthropic.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

Message Batches API — это мощный и экономически эффективный способ асинхронной обработки больших объёмов запросов Messages. Этот подход хорошо подходит для задач, не требующих немедленных ответов: большинство пакетов завершается менее чем за 1 час, при этом стоимость снижается на 50%, а пропускная способность увеличивается.

Вы можете изучить справочник API напрямую, а также воспользоваться данным руководством.

Как работает Message Batches API

Когда вы отправляете запрос в Message Batches API:

Система создаёт новый Message Batch с предоставленными запросами Messages.
Пакет затем обрабатывается асинхронно, при этом каждый запрос обрабатывается независимо.
Вы можете опрашивать статус пакета и получать результаты после завершения обработки всех запросов.

Это особенно полезно для массовых операций, не требующих немедленных результатов, например:

Масштабные оценки: эффективная обработка тысяч тестовых случаев.
Модерация контента: асинхронный анализ больших объёмов пользовательского контента.
Анализ данных: получение аналитики или сводок для больших наборов данных.
Массовая генерация контента: создание большого количества текста для различных целей (например, описания товаров, краткие изложения статей).

Ограничения пакетов

Message Batch ограничен 100 000 запросами Messages или 256 МБ по размеру — в зависимости от того, что будет достигнуто первым.
Система обрабатывает каждый пакет как можно быстрее, большинство пакетов завершается в течение 1 часа. Вы сможете получить доступ к результатам пакета, когда все сообщения будут обработаны или через 24 часа — в зависимости от того, что наступит раньше. Пакеты истекают, если обработка не завершается в течение 24 часов.
Результаты пакетов доступны в течение 29 дней после создания. После этого вы всё ещё можете просматривать пакет, но его результаты больше не будут доступны для скачивания.
Пакеты привязаны к Рабочему пространству. Вы можете просматривать все пакеты (и их результаты), созданные в Рабочем пространстве, которому принадлежит ваш API-ключ.
Ограничения скорости применяются как к HTTP-запросам Batches API, так и к количеству запросов в пакете, ожидающих обработки. См. Ограничения скорости Message Batches API. Кроме того, обработка может замедляться в зависимости от текущего спроса и объёма ваших запросов. В этом случае вы можете увидеть больше запросов, истекающих через 24 часа.
Из-за высокой пропускной способности и параллельной обработки пакеты могут незначительно превышать настроенный лимит расходов вашего Рабочего пространства.

Поддерживаемые модели

Все активные модели поддерживают Message Batches API.

Что можно включить в пакет

Любой запрос, который вы можете сделать к Messages API, может быть включён в пакет. Это включает:

Vision
Использование инструментов
Системные сообщения
Многоходовые диалоги
Любые бета-функции

Поскольку каждый запрос в пакете обрабатывается независимо, вы можете смешивать различные типы запросов в одном пакете.

Поскольку обработка пакетов может занимать более 5 минут, рассмотрите возможность использования кэширования на 1 час с кэшированием подсказок для повышения частоты попаданий в кэш при обработке пакетов с общим контекстом.

Ценообразование

Batches API предлагает значительную экономию средств. Всё использование тарифицируется по 50% от стандартных цен 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

Как использовать Message Batches API

Подготовка и создание пакета

Message Batch состоит из списка запросов на создание Message. Структура отдельного запроса включает:

Уникальный custom_id для идентификации запроса Messages
Объект params со стандартными параметрами Messages API

Вы можете создать пакет, передав этот список в параметр requests:

В этом примере два отдельных запроса объединяются в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы использовали бы при вызове Messages API.

Тестируйте запросы пакета с помощью Messages API

Валидация объекта params для каждого запроса сообщения выполняется асинхронно, а ошибки валидации возвращаются после завершения обработки всего пакета. Вы можете убедиться в правильности формирования входных данных, предварительно проверив структуру запроса с помощью Messages API.

При первом создании пакета ответ будет содержать статус обработки 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
}

Отслеживание пакета

Поле processing_status Message Batch указывает на этап обработки пакета. Оно начинается со значения in_progress, затем обновляется до ended после завершения обработки всех запросов в пакете и готовности результатов. Вы можете отслеживать состояние пакета в Консоли или с помощью конечной точки получения.

Опрос статуса завершения Message Batch

Для опроса Message Batch вам понадобится его id, который предоставляется в ответе при создании пакета или при получении списка пакетов. Вы можете реализовать цикл опроса, который периодически проверяет статус пакета до завершения обработки:

Получение списка всех Message Batches

Вы можете получить список всех Message Batches в вашем Рабочем пространстве с помощью конечной точки списка. API поддерживает пагинацию, автоматически загружая дополнительные страницы по мере необходимости:

Получение результатов пакета

После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:

Тип результата	Описание
`succeeded`	Запрос выполнен успешно. Включает результат сообщения.
`errored`	При обработке запроса возникла ошибка, и сообщение не было создано. Возможные ошибки включают недопустимые запросы и внутренние ошибки сервера. За эти запросы вам не будет выставлен счёт.
`canceled`	Пользователь отменил пакет до того, как этот запрос мог быть отправлен модели. За эти запросы вам не будет выставлен счёт.
`expired`	Пакет достиг 24-часового срока действия до того, как этот запрос мог быть отправлен модели. За эти запросы вам не будет выставлен счёт.

Вы увидите обзор результатов в поле request_counts пакета, которое показывает, сколько запросов достигло каждого из этих четырёх состояний.

Результаты пакета доступны для скачивания по свойству results_url в Message Batch, а также, если разрешения организации позволяют, в Консоли. Из-за потенциально большого размера результатов рекомендуется получать результаты потоком, а не скачивать их все сразу.

Результаты будут в формате .jsonl, где каждая строка является допустимым объектом JSON, представляющим результат одного запроса в Message Batch. Для каждого потокового результата вы можете выполнять различные действия в зависимости от его custom_id и типа результата. Вот пример набора результатов:

.jsonl file

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

Если ваш результат содержит ошибку, его result.error будет установлен в стандартную форму ошибки.

Результаты пакета могут не совпадать с порядком входных данных

Результаты пакета могут возвращаться в любом порядке и могут не совпадать с порядком запросов при создании пакета. В приведённом выше примере результат второго запроса пакета возвращается раньше первого. Для правильного сопоставления результатов с соответствующими запросами всегда используйте поле custom_id.

Отмена Message Batch

Вы можете отменить Message Batch, который в данный момент обрабатывается, с помощью конечной точки отмены. Сразу после отмены processing_status пакета будет canceling. Вы можете использовать ту же технику опроса, описанную выше, чтобы дождаться завершения отмены. Отменённые пакеты получают статус ended и могут содержать частичные результаты для запросов, которые были обработаны до отмены.

Ответ покажет пакет в состоянии canceling:

JSON

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

Использование кэширования подсказок с пакетными сообщениями

Message Batches API поддерживает кэширование подсказок, что позволяет потенциально снизить затраты и время обработки пакетных запросов. Скидки на кэширование подсказок и Message Batches могут суммироваться, обеспечивая ещё большую экономию при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются по мере возможности. Пользователи, как правило, наблюдают частоту попаданий в кэш от 30% до 98% в зависимости от характера трафика.

Чтобы максимально увеличить вероятность попаданий в кэш в пакетных запросах:

Включайте идентичные блоки cache_control в каждый запрос сообщения в пакете
Поддерживайте непрерывный поток запросов, чтобы записи кэша не истекали после 5-минутного срока жизни
Структурируйте запросы так, чтобы максимально использовать общее кэшированное содержимое

Пример реализации кэширования подсказок в пакете:

В этом примере оба запроса в пакете содержат идентичные системные сообщения и полный текст «Гордости и предубеждения», помеченный с помощью cache_control для увеличения вероятности попаданий в кэш.

Лучшие практики эффективной пакетной обработки

Чтобы получить максимальную отдачу от Batches API:

Регулярно отслеживайте статус обработки пакетов и реализуйте соответствующую логику повторных попыток для неудавшихся запросов.
Используйте значимые значения custom_id для удобного сопоставления результатов с запросами, поскольку порядок не гарантируется.
Рассмотрите возможность разбивки очень больших наборов данных на несколько пакетов для лучшей управляемости.
Выполните пробный запуск с одной формой запроса через Messages API, чтобы избежать ошибок валидации.

Устранение распространённых проблем

При возникновении неожиданного поведения:

Убедитесь, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком велик, вы можете получить ошибку 413 request_too_large.
Проверьте, что для всех запросов в пакете используются поддерживаемые модели.
Убедитесь, что каждый запрос в пакете имеет уникальный custom_id.
Убедитесь, что с момента создания пакета created_at (не времени окончания обработки ended_at) прошло менее 29 дней. Если прошло более 29 дней, результаты больше не будут доступны для просмотра.
Убедитесь, что пакет не был отменён.

Обратите внимание, что сбой одного запроса в пакете не влияет на обработку других запросов.

Хранение пакетов и конфиденциальность

Изоляция рабочего пространства: Пакеты изолированы в рамках рабочего пространства, в котором они созданы. Доступ к ним возможен только с помощью ключей API, связанных с этим рабочим пространством, или пользователей с разрешением на просмотр пакетов рабочего пространства в консоли.
Доступность результатов: Результаты пакетов доступны в течение 29 дней после создания пакета, что обеспечивает достаточно времени для их получения и обработки.

Хранение данных

Пакетная обработка хранит данные запросов и ответов до 29 дней после создания пакета. Вы можете удалить пакет сообщений в любое время после обработки с помощью конечной точки DELETE /v1/messages/batches/{batch_id}. Асинхронная обработка требует серверного хранения как входных, так и выходных данных до завершения пакета и получения результатов.

Сведения о праве на ZDR для всех функций см. в разделе API и хранение данных.

Часто задаваемые вопросы

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

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)

import anthropic

client = anthropic.Anthropic()

# Автоматически загружает дополнительные страницы по мере необходимости.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

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

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

Message Batches API

Как работает Message Batches API

Ограничения пакетов

Поддерживаемые модели

Что можно включить в пакет

Ценообразование

Как использовать Message Batches API

Подготовка и создание пакета

Отслеживание пакета

Опрос статуса завершения Message Batch

Получение списка всех Message Batches

Получение результатов пакета

Отмена Message Batch

Использование кэширования подсказок с пакетными сообщениями

Лучшие практики эффективной пакетной обработки

Устранение распространённых проблем

Хранение пакетов и конфиденциальность

Хранение данных

Часто задаваемые вопросы

Сколько времени занимает обработка пакета?

Доступен ли Batches API для всех моделей?

Можно ли использовать Message Batches API с другими функциями API?

Как Message Batches API влияет на ценообразование?

Можно ли обновить пакет после его отправки?

Существуют ли ограничения скорости Message Batches API и взаимодействуют ли они с ограничениями скорости Messages API?

Как обрабатывать ошибки в пакетных запросах?

Как Message Batches API обеспечивает конфиденциальность и разделение данных?

Можно ли использовать кэширование подсказок в Message Batches API?