Claude Batch API: скидка 50 %, расчёт с кэшем и первый пакет

Claude Batch API, официально Message Batches API, принимает обычные запросы к Messages API одним пакетом через POST /v1/messages/batches и берёт за них 50 % стандартной цены: вдвое дешевле вход, выход и все специальные токены. Плата за скидку — ожидание: по документации Anthropic о пакетной обработке большинство пакетов завершается быстрее чем за час, но гарантируется только окно в 24 часа. Если результат нужен не сразу (прогон эвалов, классификация, извлечение данных, ночные отчёты), отправляйте такие задачи пакетом и сопоставляйте ответы по custom_id.

Скидка не складывается с кэшированием сама собой. Расчёт по прайсу Anthropic на 30 октября 2026 года для 10 000 запросов на Claude Sonnet 5.5 с общим префиксом в 3 000 токенов даёт $101,00 за обычные вызовы, $50,50 за пакет без кэша, но $44,00 за обычные вызовы с работающим кэшем. Поэтому если у запросов есть общий системный промпт или документ, ставьте cache_control на этот префикс и внутри пакета: при 98 % попаданий тот же объём стоит $22,72, а 5-минутный кэш перестаёт быть убыточным уже примерно с 21 % попаданий.

Message Batches API со скидкой 50 % есть в API Anthropic, в Claude Platform on AWS и в Claude Models on Google Cloud под управлением Anthropic. Россию Anthropic не обслуживает, а у Amazon Bedrock и Google Vertex AI свои пакетные продукты с другими форматами и условиями. Команда /batch в Claude Code к Batch API отношения не имеет: это встроенный навык, который делит правку кода на 5–30 независимых частей и раздаёт их фоновым субагентам, каждому в своём git worktree. Чем вообще различаются оплата API и Claude Code, разобрано в статье Claude API и Claude Code: в чём разница и что выбрать.

Сколько экономит Claude Batch API: четыре варианта одной задачи

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

Расчёт выполнен 30 октября 2026 года по странице цен Claude API. Нагрузка: 10 000 запросов, у каждого общий префикс 3 000 токенов (инструкция и примеры), 800 токенов уникального входа и 250 токенов выхода. Множители кэша по Anthropic: запись на 5 минут — 1,25 от цены входа, на час — 2, чтение — 0,1 у Haiku 5.5, 0,05 у Sonnet 5.5 и Opus 5.5, 0,025 у Fable 5.1; по документации они перемножаются со скидкой пакета. Принято, что каждый промах кэша заново записывает префикс, а у обычных вызовов с кэшем попадания близки к 100 %, потому что запросы идут последовательно (первая запись не учтена).

Любую ячейку можно пересчитать вручную. Стоимость запроса = префикс × (доля попаданий × множитель чтения + доля промахов × множитель записи) × цена входа + уникальный вход × цена входа + выход × цена выхода. Для Sonnet 5.5 в пакете (вход $1, выход $5 за 1 млн токенов) при 30 % попаданий: 3 000 × (0,3 × 0,05 + 0,7 × 1,25) = 2 670 токенов по цене входа, то есть $0,00267, плюс $0,0008 за уникальный вход и $0,00125 за выход. Итого $0,00472 за запрос и $47,20 за 10 000 запросов.

Из таблицы следуют два вывода. В этой нагрузке на всех четырёх моделях обычные вызовы с работающим кэшем дешевле пакета без кэша (у Sonnet 5.5 — $4,40 против $5,05 за 1 000 запросов), так что пакет без кэша выигрывает у них, только если общий префикс короткий или его нет. Пакет с кэшем обгоняет их не всегда: при 30 % попаданий он на всех моделях ещё немного дороже, при 98 % — примерно вдвое дешевле. Второй вывод касается выхода: в этой нагрузке он составляет 24,8 % обычного счёта, кэш его не трогает, а пакет делит пополам, поэтому чем длиннее ответы относительно повторяющегося входа, тем больше даёт пакет даже без кэша. Если вы задаёте inference_geo: "us", все строки дополнительно умножаются на 1,1, и скидка пакета действует поверх этого множителя. Тарифы отдельных моделей подробно разобраны в статьях Цена Claude Fable 5.1 API: тарифы, кэш и расчёт счёта и Claude Sonnet 5.5: цена чтения кэша $0,10 — расчёт экономии.

Когда кэш внутри пакета окупается: от 21 % попаданий

Кэш общего префикса внутри пакета выгоден, если попаданий больше примерно пятой части для 5-минутной записи и примерно половины для часовой, на всех четырёх моделях из таблицы выше.

Порог выводится из тех же множителей. Без кэша префикс в каждом запросе стоит 1 цену входа. С кэшем попадание стоит r (0,05 у Sonnet 5.5 и Opus 5.5), а промах — w: 1,25 для 5-минутной записи или 2 для часовой, потому что префикс записывается заново. Кэш выгоден, когда h × r + (1 − h) × w меньше 1, то есть при доле попаданий h больше (w − 1) / (w − r). Для 5-минутной записи это 21,7 % у Haiku 5.5, 20,8 % у Sonnet 5.5 и Opus 5.5 и 20,4 % у Fable 5.1; для часовой — 52,6 %, 51,3 % и 50,6 % соответственно. Скидка пакета в этой формуле сокращается, поэтому пороги одинаковы и для пакета, и для обычных вызовов.

Свою долю попаданий заранее не узнать. В разделе о кэшировании в пакетах Anthropic пишет, что кэш там работает по принципу best effort: запросы обрабатываются параллельно и в любом порядке, и пользователи обычно видят от 30 до 98 % попаданий. Нижняя граница этого диапазона выше порога для 5-минутной записи, поэтому при типичной доле попаданий такой кэш на общем префиксе окупается. Часовой кэш при 30 % попаданий, наоборот, выходит примерно на четверть дороже пакета без кэша на всех четырёх моделях. Anthropic советует рассмотреть часовой кэш для пакетов с общим контекстом, потому что пакет может обрабатываться дольше 5 минут; это оправдано, только если часовая запись действительно поднимет попадания выше половины, а в расчёте выше этот эффект не учтён.

Чтобы попаданий было больше, Anthropic рекомендует ставить одинаковые блоки cache_control в каждый запрос, держать как можно больше общего содержимого в начале запроса и отправлять запросы ровным потоком, чтобы 5-минутные записи не успевали истечь. Прогреть кэш запросом с max_tokens: 0 внутри пакета нельзя. Как включается кэш, какие у него TTL и как читать поля cache_read_input_tokens, показано в статье Claude prompt caching: кэширование промптов, TTL, цены и тест.

Как отправить первый пакет и собрать результаты по custom_id

Пакет создаётся одним вызовом client.messages.batches.create, после чего его статус нужно опрашивать, пока processing_status не станет ended, и только потом обходить результаты, сверяя каждый с вашим custom_id. Ключ API тот же, что для обычных вызовов; как его получить, описано в статье Claude API key: бесплатный кредит, цены и как купить доступ.

1. Отправьте один запрос нужной формы через обычный Messages API. Параметры внутри пакета проверяются асинхронно, и ошибка валидации всплывёт, только когда закончится весь пакет.
2. Соберите список запросов. У каждого есть custom_id (1–64 символа: латинские буквы, цифры, - и _, уникальный в пределах пакета) и params с теми же полями, что у обычного запроса, включая max_tokens не меньше 1.
3. Создайте пакет через client.messages.batches.create(requests=...) и сохраните batch.id.
4. Опрашивайте client.messages.batches.retrieve(batch.id), например раз в минуту, пока processing_status не станет ended. Вебхук в документации не описан. Счётчики request_counts по типам результатов остаются нулевыми до окончания всего пакета, так что забрать готовую часть раньше не получится.
5. Обходите client.messages.batches.results(batch.id) потоком и сопоставляйте каждую строку по custom_id: порядок результатов не совпадает с порядком запросов.
6. Разложите неуспешные запросы на «переотправить» и «исправить» и сохраните ответы у себя, пока не истёк срок хранения результатов.

import time
import anthropic

client = anthropic.Anthropic()  # ключ берётся из ANTHROPIC_API_KEY

def make_request(custom_id: str, text: str) -> dict:
    return {
        "custom_id": custom_id,  # 1–64 символа: буквы, цифры, - и _
        "params": {
            "model": "claude-haiku-5-5",
            "max_tokens": 300,
            "messages": [{"role": "user", "content": text}],
        },
    }

def run_batch(requests: list[dict], poll_seconds: int = 60) -> tuple[dict, list[str], list[str]]:
    batch = client.messages.batches.create(requests=requests)
    print("created", batch.id, batch.processing_status)
    while batch.processing_status != "ended":
        time.sleep(poll_seconds)
        batch = client.messages.batches.retrieve(batch.id)
        print("status", batch.processing_status, batch.request_counts)
    done, retry, fix = {}, [], []
    for item in client.messages.batches.results(batch.id):  # порядок не гарантирован
        r = item.result
        if r.type == "succeeded":
            done[item.custom_id] = r.message.content[0].text
        elif r.type == "expired":
            retry.append(item.custom_id)          # до модели не дошёл, не оплачивается
        elif r.type == "errored" and r.error.error.type == "invalid_request_error":
            fix.append(item.custom_id)            # то же тело снова не пройдёт
        elif r.type == "errored":
            retry.append(item.custom_id)          # ошибка на стороне сервера, можно отправить снова
    return done, retry, fix

Функция возвращает готовые ответы, список custom_id для повторной отправки и список запросов, которые сначала нужно исправить. Повтор — это новый пакет только из retry: снова вызовите run_batch для этих custom_id и добавьте результаты к done.

30 октября 2026 года этот код прогнан от начала до конца на Python SDK anthropic 2.3.0, но против локального мок-сервера, который повторяет документированные эндпоинты и форму ответов, а не против серверов Anthropic. Из пяти запросов два вернулись succeeded; один errored с серверной ошибкой и один expired ушли во второй пакет и там завершились успешно, а один errored с invalid_request_error остался в списке на исправление. Результаты пришли в обратном порядке и сошлись по custom_id, а пока пакет обрабатывался, счётчики показывали processing=5 и нули по остальным типам. Реальное время обработки, точные тексты ошибок валидации и списания этот прогон не проверяет. Те же методы create, retrieve, list, cancel, delete и results есть в TypeScript SDK @anthropic-ai/sdk 1.3.0 (оба SDK выпущены 23 октября 2026 года).

succeeded, errored, canceled, expired: что переотправлять и что оплачивается

Платите вы только за succeeded: по документации Anthropic запросы с результатом errored, canceled и expired не тарифицируются. Переотправлять без изменений можно expired и серверные ошибки, а запрос с invalid_request_error сначала нужно исправить.

Ошибка одного запроса не влияет на остальные запросы пакета. Отправленный пакет изменить нельзя: его можно только отменить через cancel, после чего статус становится canceling, а затем ended, и в результатах остаются ответы, обработанные до отмены. Отмена может сработать не сразу. После окончания обработки пакет можно удалить запросом DELETE /v1/messages/batches/{id}; идущий пакет перед удалением нужно отменить.

Лимиты Message Batches API: 100 000 запросов, 256 МБ, 24 часа, 29 дней

Один пакет ограничен 100 000 запросов или 256 МБ, смотря что наступит раньше; необработанные за 24 часа запросы истекают, а результаты можно скачать в течение 29 дней с момента создания пакета. Все значения ниже — из документации Anthropic по состоянию на 30 октября 2026 года.

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

Новые организации могут начинать с уровня Evaluation, у которого пакетные лимиты ниже и не опубликованы; уровень Custom обсуждается с отделом продаж. Пакеты не расходуют лимиты обычных вызовов Messages API, поэтому перенос несрочной части нагрузки в пакет освобождает синхронный лимит. Если упираетесь именно в него, разбор есть в статье Claude API Rate Limit Reached: сначала найдите владельца лимита.

Почему пакет Claude идёт часами или истекает

Anthropic обещает не скорость, а окно: «большинство» пакетов завершается меньше чем за час, но обработка может замедлиться в зависимости от текущей нагрузки и вашего объёма запросов, и тогда больше запросов истекает через 24 часа. Цифр о таком замедлении Anthropic не публикует, а в FAQ прямо сказано, что пакет может истечь, не завершившись.

Сторонние замеры дают порядок величин, но не гарантию. Пользователь Hacker News erans 27 апреля 2026 года писал, что, пропуская каждый шаг агента через Batch API, получал результат пакета из одного запроса обычно за 90–120 секунд, а пакеты на Haiku казались ему медленнее, чем на Sonnet и Opus; сам автор называет эти наблюдения нестрогими. В руководстве developersdigest (обновлено 18 октября 2026 года) медиана завершения в их замерах — от 5 до 30 минут. На странице статуса Claude инциденты с пакетной обработкой упоминаются только в ноябре 2024 года (ошибки 4 ноября и задержки 6–7 ноября); в 2025 и 2026 годах таких записей нет, но отсутствие инцидентов не исключает замедлений из-за нагрузки.

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

Что можно отправить пакетом, а что вернёт ошибку валидации

В пакет можно положить почти любой запрос к Messages API, включая изображения, инструменты, многоходовые диалоги и расширенное мышление; ошибку валидации вернут только stream: true, speed, fallbacks и max_tokens: 0. Разные типы запросов можно смешивать в одном пакете, потому что каждый обрабатывается независимо.

Серверный инструмент web search внутри пакетов ограничивается по скорости на уровне организации и повторяется автоматически. Генерация на 300 000 токенов, по документации, может занять больше часа, а цена у неё обычная пакетная.

Где действует скидка 50 %: Anthropic, AWS, Google Cloud, Bedrock и шлюзы

Message Batches API со скидкой 50 % работает в трёх местах: в API Anthropic, в Claude Platform on AWS и в Claude Models on Google Cloud под управлением Anthropic. Для API Anthropic нужен аккаунт в Console, а по справке Anthropic о поддерживаемых странах по состоянию на 22 октября 2026 года в списке нет России, Беларуси, материкового Китая, Гонконга и Венесуэлы. Создавать аккаунт и пользоваться им могут только те, кто физически находится в поддерживаемой стране, поэтому из России API Anthropic недоступен. Claude Platform on AWS и вариант на Google Cloud тоже работают под управлением Anthropic, и их доступность для вашей страны определяют условия этих платформ.

Amazon Bedrock — не то же самое, что Claude Platform on AWS. У него своя пакетная обработка (batch inference): по странице цен Amazon Bedrock для отдельных моделей Anthropic она на 50 % дешевле on-demand, но вход другой — файл JSONL в S3, по строке {"recordId", "modelInput"} на запрос, минимум 100 записей на задание для Claude, до 100 000 записей и 5 ГБ. По состоянию на 30 октября 2026 года в списке моделей Bedrock с пакетным режимом самые новые из Claude — Opus 5, Opus 4.6, Sonnet 4.6 и Haiku 4.5, а моделей 5.5 и Fable нет; вызов инструментов в пакете доступен только в формате InvokeModel, не в Converse.

Google Vertex AI (под управлением Google) принимает пакетные задания для Claude из таблицы BigQuery или JSONL в Cloud Storage, с custom_id и anthropic_version: "vertex-2023-10-16" в каждой строке. Глобальный эндпоинт для таких заданий не поддерживается, по умолчанию на проект разрешено 4 параллельных пакетных задания, а в документации Vertex AI о пакетных предсказаниях для Claude (обновлена 28 октября 2026 года) перечислены Sonnet 5.5, Opus 5.5, Haiku 5.5, Fable 5.1 и Fable 5. Размер пакетной скидки на Vertex AI смотрите в прайсе Google для своей модели.

Шлюзы, у которых этого эндпоинта нет, скидку не дают. 30 октября 2026 года запросы GET /v1/messages/batches, POST /v1/messages/batches и GET /v1/messages/batches/{id} к laozhang.ai вернули HTTP 404 Invalid URL, то есть пакетной обработки Claude там нет. Любой шлюз можно проверить тем же способом: если GET /v1/messages/batches?limit=1 возвращает 404, отправить пакет через него не получится.

Примечание: laozhang.ai — наш собственный сервис; его цены — наши тарифы, а не независимое сравнение.