Представьте, что вам надо прогнать через нейросеть 50 тысяч отзывов: каждый разметить по тональности, вытащить суть, сложить в таблицу. Если слать запросы по одному и ждать ответ на каждый, вы потратите кучу времени и заплатите полную цену. А можно отдать все 50 тысяч одним списком, заняться своими делами и забрать готовые ответы через час. Причём вдвое дешевле.
Это и есть batch API (пакетная обработка) в Claude. В Anthropic эта штука называется Message Batches API. В статье разберём по шагам: что это такое, как устроено, сколько стоит, какие у него лимиты и где новички спотыкаются. Будут примеры кода, но без них тоже всё понятно.
Если вы только знакомитесь с Claude и пока не уверены, что такое API и чат-бот от Anthropic, начните с обзорной статьи «Что такое Claude от Anthropic»: там разобрали модель, чат и API простыми словами.
Статья пригодится не только программистам. Массовую обработку текста через batch API сегодня запускают аналитики, маркетологи, контент-менеджеры, исследователи: везде, где надо прогнать через нейросеть много однотипных задач и не переплатить.
А если хочется освоить работу с нейросетями системно, загляните в нашу подборку курсов по нейросетям и искусственному интеллекту: там почти 600 программ от коротких интенсивов до годовых.
КурсыСравнение 23 курсов по ClaudeЦены, школы, длительность, рассрочка
Что такое batch API в Claude простыми словами
Начнём с базы. API (Application Programming Interface) — это способ, которым ваша программа разговаривает с нейросетью без чата и кнопок: отправляет текст запроса, получает текст ответа. Обычно это работает синхронно: вы шлёте один запрос и ждёте, пока Claude ответит, и только потом отправляете следующий.
Хорошая аналогия — поход в банк. Синхронный запрос похож на живую очередь: подошли к окошку, постояли, получили ответ, ушли. Удобно, когда у вас один вопрос и ответ нужен прямо сейчас. А вот если вопросов тысяча, стоять у окошка с каждым по очереди невыносимо.
Пакетная обработка работает иначе. Вы оставляете весь список запросов разом, как будто берёте талончик с надписью «приходите за результатом позже». Claude разбирает ваш список в фоне, а вы возвращаетесь, когда всё готово. Такой режим называется асинхронным: ответ приходит с задержкой, через какое-то время после отправки.
Message Batches API — это и есть инструмент Anthropic для такого режима. Вы складываете много запросов к Claude в один пакет (по-английски batch, отсюда и название), отправляете его одним обращением и забираете все ответы, когда обработка закончится. Каждый запрос внутри пакета считается отдельно и независимо от соседних.
Коротко. Обычный API — это живая очередь по одному запросу. Batch API — это «оставьте список, заберите всё позже». Второй режим вдвое дешевле и заточен под объём.
Зачем нужна пакетная обработка
Две причины, по которым люди вообще связываются с batch API: цена и объём.
Цена. Любой запрос через пакетную обработку стоит на 50 % дешевле обычного. Скидка действует и на входные токены (ваш текст запроса), и на выходные (ответ модели). Если не помните, что такое токен и почему за него платят, у нас есть отдельный разбор: «Что такое токен в нейросети». Когда задач тысячи, эти 50 % превращаются в ощутимые деньги.
Объём и скорость. Пакетная обработка рассчитана на большие массивы и даёт более высокую пропускную способность, чем поток одиночных запросов. Вы не упираетесь в ожидание ответа на каждый запрос и не пишете сложную логику параллельной отправки: всё это берёт на себя сервер Anthropic.
Где это применяют:
- Массовые тесты и оценки: прогнать тысячи тестовых примеров и проверить, как модель справляется с задачей.
- Модерация контента: проверить большой поток пользовательских сообщений или комментариев на нарушения.
- Аналитика данных: сделать выжимки, краткие итоги или разметку для большого набора документов.
- Массовая генерация текста: описания товаров, аннотации статей, варианты заголовков пачкой.
Главное условие: ответы не нужны сию секунду. Если вы строите чат, где пользователь ждёт реакцию на экране, batch API не подходит, там нужен синхронный режим. А для фоновой обработки «на ночь» это самый удобный вариант.
Как работает batch API — по шагам
Весь цикл пакетной обработки укладывается в четыре шага.
Шаг 1. Вы собираете пакет. Складываете список запросов и отправляете его на специальный адрес внутри API (его называют эндпоинтом): /v1/messages/batches. В ответ сразу приходит идентификатор пакета вида msgbatch_… и его статус.
Шаг 2. Claude обрабатывает пакет в фоне. Сервер берёт ваши запросы и считает их асинхронно, каждый сам по себе. Сразу после создания у пакета статус in_progress («в работе»).
Шаг 3. Вы проверяете статус. Время от времени спрашиваете у API: «пакет готов?». Этот периодический опрос статуса по-английски называют polling. Когда все запросы досчитаны, статус меняется на ended («завершён»).
Шаг 4. Вы забираете результаты. Как только статус стал ended, скачиваете файл с ответами и раскладываете их по своим задачам.
Внутри статуса пакет показывает счётчик request_counts: сколько запросов ещё в работе, сколько успешно посчитано, сколько с ошибкой, сколько отменено и сколько истекло по времени. По нему удобно следить за прогрессом большого пакета.
Важный нюанс. Падение одного запроса не роняет весь пакет. Если из 10 тысяч запросов 12 оказались битыми, остальные 9988 спокойно досчитаются и вернутся к вам.
Как отправить первый батч
Пакет состоит из списка запросов. У каждого запроса всего два обязательных поля:
custom_id— ваша собственная метка для запроса, чтобы потом узнать его в ответах. От 1 до 64 символов, только латиница, цифры, дефис и подчёркивание. Например,otzyv-001.params— сам запрос с обычными параметрами Messages API: какая модель, сколько токенов в ответе (max_tokens), текст сообщения.
Вот как создать пакет из двух запросов через cURL (это утилита командной строки для отправки запросов на сервер):
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": "otzyv-001",
"params": {
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Определи тональность отзыва: «Доставка быстрая, всё понравилось»"}
]
}
},
{
"custom_id": "otzyv-002",
"params": {
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Определи тональность отзыва: «Ждал две недели, товар бракованный»"}
]
}
}
]
}'То же самое на Python через официальную библиотеку Anthropic (SDK — это готовый набор кода, который избавляет от ручной возни с запросами):
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="otzyv-001",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Определи тональность отзыва: ..."}],
),
),
Request(
custom_id="otzyv-002",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Определи тональность отзыва: ..."}],
),
),
]
)
print(message_batch)Кроме Python, у Anthropic есть готовые библиотеки для TypeScript, Go, Java, C#, PHP и Ruby, так что подойдёт почти любой популярный язык.
Сначала проверьте один запрос на обычном API
Маленький совет. Правильность каждого запроса в пакете проверяется только в процессе обработки, и ошибки вы увидите ближе к концу. Поэтому сначала отправьте один такой же запрос через обычный синхронный Messages API: убедитесь, что структура верная, и только потом запускайте пакет на тысячи строк. Эта пробная отправка по-английски называется dry run.
Как отследить статус и забрать результаты
После создания пакета у вас на руках его идентификатор. Дальше идёт опрос статуса в цикле: спросили, получили in_progress, подождали минуту, спросили снова. Когда придёт ended, пакет готов.
import anthropic
import time
client = anthropic.Anthropic()
batch_id = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
while True:
batch = client.messages.batches.retrieve(batch_id)
if batch.processing_status == "ended":
break
print("Пакет ещё обрабатывается...")
time.sleep(60)Когда обработка закончилась, у каждого запроса появляется результат одного из четырёх типов:
| Тип результата | Что значит | Берут ли деньги |
|---|---|---|
succeeded |
Запрос успешно обработан, внутри — ответ модели | Да |
errored |
Ошибка: неверный запрос или сбой на сервере, ответа нет | Нет |
canceled |
Вы отменили пакет до того, как запрос дошёл до модели | Нет |
expired |
Пакет не успел досчитаться за 24 часа | Нет |
Приятная деталь: за неуспешные запросы (errored, canceled, expired) денег не берут. Платите только за то, что посчиталось.
Сами ответы приходят файлом в формате JSONL. Это обычный текстовый файл, где каждая строка — отдельный кусочек данных в формате JSON (способ записи структурированной информации, который понимают почти все языки программирования). Одна строка файла — один ответ на один ваш запрос.
Запомните про порядок. Ответы в файле могут идти не в том порядке, в каком вы отправляли запросы. Сопоставлять их со своими задачами надо строго по полю
custom_id, а не по номеру строки. Поэтому метки и должны быть осмысленными.
Если пакет вдруг стал не нужен, его можно отменить специальным запросом. Сразу после отмены статус станет canceling, а затем перейдёт в ended: то, что успело посчитаться до отмены, к вам всё равно вернётся.
Лимиты, сроки и цены
Прежде чем запускать что-то большое, держите в голове рамки пакетной обработки.
| Параметр | Значение |
|---|---|
| Запросов в одном пакете | до 100 000 |
| Размер пакета | до 256 МБ |
| Время обработки | обычно меньше часа, максимум 24 часа |
| Что после 24 часов | недосчитанные запросы получают статус expired |
| Хранение результатов | 29 дней с момента создания пакета |
| Доступ к пакету | в пределах одного воркспейса (рабочего пространства аккаунта) |
| Поддержка моделей | все активные модели Claude |
Лимит срабатывает по первому достигнутому порогу: 100 000 запросов или 256 МБ, что наступит раньше. Если данных больше, разбейте их на несколько пакетов, так и управлять проще.
Теперь про деньги. Скидка 50 % хорошо видна, если поставить рядом обычную и пакетную цену. Вот стоимость за 1 миллион токенов для актуальных моделей на 2026 год:
| Модель | Обычный API (вход / выход) | Batch API (вход / выход) |
|---|---|---|
| Claude Opus 4.8 | $5 / $25 | $2,50 / $12,50 |
| Claude Sonnet 4.6 | $3 / $15 | $1,50 / $7,50 |
| Claude Haiku 4.5 | $1 / $5 | $0,50 / $2,50 |
Если непонятно, какую модель брать: для массовой рутины вроде разметки или коротких выжимок обычно хватает Claude Haiku 4.5, она самая дешёвая и быстрая. Когда задача сложнее и важно качество рассуждений, берите Claude Sonnet 4.6. Для самых тяжёлых случаев подойдёт Claude Opus 4.8.
Что можно и нельзя класть в батч
Почти всё, что вы умеете делать с обычным Messages API, работает и в пакете. Поскольку запросы считаются независимо, в одном пакете можно смешивать совсем разные задачи.
| Можно положить в пакет | Нельзя |
|---|---|
| Картинки на вход (vision) | Потоковую выдачу ответа по словам (stream) |
| Инструменты и веб-поиск (tool use) | Ускоренный режим (speed) |
| Системные сообщения | Сохранение диалога на сервере (store) |
| Многоходовые диалоги | Запрос с max_tokens: 0 |
| Расширенное размышление (extended thinking) | Часть служебных подсказок планировщику |
Логика запретов простая: всё, что завязано на мгновенный синхронный ответ (поток по словам, ускорение), в асинхронном пакете теряет смысл. У каждого запроса max_tokens должен быть хотя бы 1: ноль не поддерживается.
Теперь про кэширование промптов (prompt caching). Это механизм, который запоминает повторяющуюся часть запроса, чтобы не пересчитывать её каждый раз. Скидка за кэш складывается со скидкой за пакет, так что вместе они экономят ещё сильнее. Правда, в асинхронном режиме попадание в кэш не гарантировано: оно работает по возможности.
Для тех, кому нужны длинные ответы, есть бета-режим расширенного вывода: специальный заголовок поднимает потолок max_tokens до 300 000 токенов для моделей Opus 4.8, Opus 4.7, Opus 4.6 и Sonnet 4.6. Бета-заголовок — это просто пометка в запросе, что вы хотите включить экспериментальную возможность. Пригодится для книг, объёмной документации и больших выгрузок данных.
7 частых ошибок новичков
На этих граблях спотыкаются почти все, кто запускает пакетную обработку впервые.
Ошибка 1 — ждать ответы в том же порядке
Результаты приходят вперемешку. Если раскладывать их по номеру строки, перепутаете данные. Всегда сопоставляйте по custom_id.
Ошибка 2 — делать одинаковые custom_id
Метка у каждого запроса должна быть уникальной. Два одинаковых custom_id, и вы не поймёте, где чей ответ.
Ошибка 3 — превысить размер пакета
Если суммарный объём перевалит за 256 МБ, сервер вернёт ошибку 413 (request_too_large). Большие массивы заранее режьте на части.
Ошибка 4 — запускать тысячи строк без проверки
Один битый шаблон, и весь пакет вернётся с ошибками валидации, а время потеряно. Сначала прогоните один запрос через обычный API.
Ошибка 5 — путать пакетную обработку с чатом
Batch API не для интерфейсов, где человек ждёт ответ на экране. Ответ может прийти и через час. Для живого общения нужен синхронный режим.
Ошибка 6 — забыть про окно 24 часа
Если пакет не досчитался за сутки, остаток помечается как expired. Планируйте объём так, чтобы уложиться, особенно если включаете длинные ответы.
Ошибка 7 — потерять результаты после 29 дней
Ответы хранятся 29 дней с момента создания пакета. Не забирайте их месяцами — скачивайте и складывайте к себе сразу.
Batch API в Claude, OpenAI и Gemini — чем похожи
Пакетная обработка есть не только у Anthropic. Похожие инструменты предлагают OpenAI и Google. Подход у всех трёх один и тот же, и если вы освоили один, остальные дадутся легко.
| Параметр | Claude (Anthropic) | OpenAI | Gemini (Google) |
|---|---|---|---|
| Скидка к цене | 50 % | 50 % | 50 % |
| Режим | асинхронный | асинхронный | асинхронный |
| Окно обработки | 24 часа | 24 часа | 24 часа |
| Формат результатов | JSONL | JSONL | JSONL |
| Метка запроса | custom_id |
custom_id |
ключ запроса |
Различия в основном в деталях: как именно загружать запросы и какие у провайдера лимиты. Сама идея «собери список, отправь пачкой, забери позже за полцены» везде одинаковая.
Где научиться работать с нейросетями и API
Batch API — это уже прикладной навык поверх базы: понимания, как устроены нейросети, токены, промпты и работа с API. Если хочется выстроить эту базу по порядку, а не собирать по кускам из документации, удобнее один раз пройти нормальный курс.
Мы собрали подборку программ по нейросетям и искусственному интеллекту: от коротких курсов «с нуля» до глубокого обучения разработке с AI.
| Курс | Школа | Стоимость со скидкой | В рассрочку | Длительность | Обзор курса от Checkroi |
|---|---|---|---|---|---|
| Нейросети для изображений и видео Перейти на сайт курса |  Эдюсон | 69 100 ₽ | 5758 ₽/мес. | 2 месяца | Обзор курса |
| Нейросети: практический курс Перейти на сайт курса |  Skypro | 25 990 ₽ | 181 667 ₽/мес. | 3 месяца | Обзор курса |
| Нейросети для рабочих задач Перейти на сайт курса |  Skillbox | 29 800 ₽ | 2483 ₽/мес. | 1 месяц | Обзор курса |
| Нейросети. Практический курс Перейти на сайт курса | Skillbox | 74 900 ₽ | 6242 ₽/мес. | 3 месяца | Обзор курса |
| Нейросети для каждого: как решать рабочие задачи быстрее Перейти на сайт курса |  Нетология | 37 300 ₽ | 2763 ₽/мес. | 6 недель | Обзор курса |
| Нейросети на практике Перейти на сайт курса | Эдюсон | 54 515 ₽ | 4542 ₽/мес. | 2 месяца | Обзор курса |
| Нейросети для дизайнера Перейти на сайт курса | Skillbox | 84 272 ₽ | 3831 ₽/мес. | 4 месяца | Обзор курса |
| Нейросети для анализа данных Перейти на сайт курса | Нетология | 31 700 ₽ | 2351 ₽/мес. | 8 недель | Обзор курса |
| Магистратура «Прикладной искусственный интеллект» с УрФУ Перейти на сайт курса | Нетология | 162 500 ₽ | 244 ₽/мес. | 24 месяца | Обзор курса |
| Нейросети для дизайна Перейти на сайт курса |  Практикум | 64 000 ₽ | 2612 ₽/мес. | 2 месяца | Обзор курса |
Больше программ — в полном каталоге курсов по нейросетям и искусственному интеллекту
Дальше по теме почитайте, как устроены размышления нейросетей простыми словами, и загляните в подборку промптов для программистов в Claude Code и Cursor: вместе с пакетной обработкой это хороший набор для повседневной работы с Claude.
![Обложка: OpenAI API — что это и как пользоваться новичку в [current year]](https://selcdn.checkroi.ru/wp-content/uploads/og-images/og-cover-76438-1780955794.webp "Статья: OpenAI API — что это и как пользоваться новичку в 2026")
![Обложка: Бесплатные нейросети в [current year] — топ для каждой задачи](https://selcdn.checkroi.ru/wp-content/uploads/og-images/og-cover-65257-1780955258.webp "Статья: Бесплатные нейросети в 2026 — топ для каждой задачи")
