---
title: Пакетная обработка
url: https://platform.claude.com/docs/ru/build-with-claude/batch-processing
description: Асинхронно обрабатывайте большие объёмы запросов Messages с помощью Message Batches API, сокращая затраты на 50% и повышая пропускную способность.
---
Пакетная обработка (batch processing) — это мощный подход для эффективной обработки больших объёмов запросов. Вместо обработки запросов по одному с немедленными ответами пакетная обработка позволяет отправлять несколько запросов вместе для асинхронной обработки. Этот паттерн особенно полезен, когда:
* Вам нужно обработать большие объёмы данных
* Немедленные ответы не требуются
* Вы хотите оптимизировать затраты
* Вы проводите крупномасштабные оценки или анализы
Message Batches API — первая реализация этого паттерна от Anthropic.
Чтобы узнать, как «zero data retention» (нулевое хранение данных), или ZDR, применяется к этой функции, см. раздел [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
# Message Batches API
Message Batches API — это мощный и экономичный способ асинхронной обработки больших объёмов запросов [Messages](https://platform.claude.com/docs/ru/api/messages/create). Этот подход хорошо подходит для задач, не требующих немедленных ответов: большинство пакетов завершаются менее чем за 1 час, при этом затраты снижаются на 50%, а пропускная способность увеличивается.
В дополнение к этому руководству вы можете [изучить справочник API напрямую](https://platform.claude.com/docs/ru/api/messages/batches/create).
## Как работает Message Batches API
Когда вы отправляете запрос в Message Batches API:
1. Система создаёт новый Message Batch с предоставленными запросами Messages.
2. Затем пакет обрабатывается асинхронно, причём каждый запрос обрабатывается независимо.
3. Вы можете опрашивать статус пакета и получать результаты, когда обработка всех запросов завершена.
Это особенно полезно для массовых операций, не требующих немедленных результатов, таких как:
* Крупномасштабные оценки: эффективная обработка тысяч тестовых случаев.
* Модерация контента: асинхронный анализ больших объёмов пользовательского контента.
* Анализ данных: генерация выводов или сводок для больших наборов данных.
* Массовая генерация контента: создание больших объёмов текста для различных целей (например, описания товаров, краткие изложения статей).
### Ограничения пакетов
* Message Batch ограничен либо 100 000 запросов Message, либо размером 256 МБ — в зависимости от того, что будет достигнуто раньше.
* Система обрабатывает каждый пакет максимально быстро, большинство пакетов завершаются в течение 1 часа. Вы можете получить доступ к результатам пакета, когда все сообщения будут обработаны или по истечении 24 часов — в зависимости от того, что наступит раньше. Срок действия пакетов истекает, если обработка не завершается в течение 24 часов.
* Результаты пакета доступны в течение 29 дней после создания. После этого вы по-прежнему сможете просматривать пакет, но его результаты больше не будут доступны для загрузки.
* Пакеты привязаны к [рабочему пространству (Workspace)](https://platform.claude.com/settings/workspaces). Вы можете просматривать все пакеты (и их результаты), созданные в рабочем пространстве, в котором выполняется ваш запрос.
* «Rate limits» (ограничения скорости) применяются как к HTTP-запросам Batches API, так и к количеству запросов внутри пакета, ожидающих обработки. См. [ограничения скорости Message Batches API](https://platform.claude.com/docs/ru/api/rate-limits#message-batches-api). Кроме того, обработка может замедляться в зависимости от текущего спроса и объёма ваших запросов. В этом случае вы можете увидеть больше запросов, срок действия которых истекает через 24 часа.
* Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить настроенный [лимит расходов](https://platform.claude.com/settings/billing) вашего рабочего пространства.
* Каждый запрос в пакете должен иметь `max_tokens` не менее `1`. `max_tokens: 0` ([предварительный прогрев кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pre-warming-the-cache)) не поддерживается внутри пакета, поскольку эфемерная запись кэша, созданная во время пакетной обработки, скорее всего, истечёт до выполнения последующего запроса.
### Поддерживаемые модели
Все [активные модели](https://platform.claude.com/docs/ru/models/overview) поддерживают Message Batches API.
### Что можно включать в пакет
Практически любой запрос, который вы можете отправить в Messages API, можно включить в пакет. Это включает:
* Зрение (vision)
* Использование инструментов (tool use), включая все [серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, advisor и поиск инструментов)
* Системные сообщения
* Многоходовые диалоги
* Расширенные размышления (extended thinking)
* Большинство бета-функций
Поскольку каждый запрос в пакете обрабатывается независимо, вы можете комбинировать разные типы запросов в одном пакете.
Небольшое количество параметров Messages API **не** поддерживается в пакетных запросах. Включение любого из них возвращает ошибку валидации:
| Параметр | Причина |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `stream: true` | Результаты пакета возвращаются одним файлом, а не потоком. |
| `speed` ([Быстрый режим](https://platform.claude.com/docs/ru/build-with-claude/fast-mode)) | Быстрый режим оптимизирует «latency» (задержку) синхронных запросов, что неприменимо к асинхронной пакетной обработке. |
| `max_tokens: 0` | См. [Ограничения пакетов](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#batch-limitations). |
Поскольку обработка пакетов может занимать более 5 минут, рассмотрите использование [1-часовой длительности кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration) с кэшированием подсказок для повышения частоты попаданий в кэш при обработке пакетов с общим контекстом.
## Цены
Batches API обеспечивает значительную экономию. Всё использование оплачивается по ставке 50% от стандартных цен API.
| Model | Batch input | Batch output |
| :----------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |
| Claude Fable 5.1 | $5 / MTok | $25 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok |
| Claude Fable 5 | $5 / MTok | $25 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok |
| Claude Opus 5.5 | $2 / MTok | $10 / MTok |
| Claude Opus 5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5.5 | $1 / MTok | $5 / MTok |
| Claude Sonnet 5 | $1 / MTok | $5 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.05 / MTok | $0.25 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.25 / MTok | $1.25 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $0.40 / MTok | $2 / MTok |
* **MTok:** Million tokens. $5 / MTok is $5 for every million tokens.
* **Limited access:** Available only to organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). To request access, apply to the program that covers your use case.
* **Retired:** May still be available on other cloud platforms. See [Model deprecations](https://platform.claude.com/docs/ru/about-claude/model-deprecations) for more.
## Как использовать Message Batches API
### Подготовка и создание пакета
Message Batch состоит из списка запросов на создание Message. Структура отдельного запроса включает:
* Уникальный `custom_id` для идентификации запроса Messages. Должен содержать от 1 до 64 символов и состоять только из буквенно-цифровых символов, дефисов и подчёркиваний (соответствовать `^[a-zA-Z0-9_-]{1,64}$`).
* Объект `params` со стандартными параметрами [Messages API](https://platform.claude.com/docs/ru/api/messages/create)
Вы можете [создать пакет](https://platform.claude.com/docs/ru/api/messages/batches/create), передав этот список в параметр `requests`:
```bash 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": "my-first-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-5-5
max_tokens: 1024
messages:
- role: user
content: Hello, world
- custom_id: my-second-request
params:
model: claude-opus-5-5
max_tokens: 1024
messages:
- role: user
content: Hi again, friend
YAML
```
```python Python
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="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, world" }]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hi again, friend" }]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
AnthropicClient client = new();
var batch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hello, world" }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hi again, friend" }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go
client := anthropic.NewClient()
batch, _ := client.Messages.Batches.New(context.Background(),
anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hello, world"),
),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hi again, friend"),
),
},
},
},
},
})
fmt.Println(batch.ID)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello, world")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hi again, friend")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(params);
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$batch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hello, world']
]
]
],
[
'custom_id' => 'my-second-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hi again, friend']
]
]
]
],
);
echo $batch->id;
```
```ruby Ruby
client = Anthropic::Client.new
batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{ role: "user", content: "Hello, world" }
]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{ role: "user", content: "Hi again, friend" }
]
}
}
]
)
puts batch
```
В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный `custom_id` и содержит стандартные параметры, которые вы использовали бы для вызова Messages API.
**Тестируйте пакетные запросы с помощью Messages API**
Валидация объекта `params` для каждого запроса сообщения выполняется асинхронно, а ошибки валидации возвращаются после завершения обработки всего пакета. Вы можете убедиться, что правильно формируете входные данные, предварительно проверив структуру запроса с помощью [Messages API](https://platform.claude.com/docs/ru/api/messages/create).
При первоначальном создании пакета ответ имеет статус обработки `in_progress`.
```json Output
{
"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`, когда все запросы в пакете завершили обработку и результаты готовы. Вы можете отслеживать состояние пакета, посетив [Console](https://platform.claude.com/settings/workspaces/default/batches) или используя [эндпоинт получения](https://platform.claude.com/docs/ru/api/messages/batches/retrieve).
#### Опрос завершения Message Batch
Для опроса Message Batch вам понадобится его `id`, который предоставляется в ответе при создании пакета или при получении списка пакетов. Вы можете реализовать цикл опроса, который периодически проверяет статус пакета до завершения обработки:
```bash cURL
#!/bin/sh
# ...
# Проверьте статус; повторяйте, пока processing_status не станет "ended"
curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
| jq -r '.processing_status'
```
```bash CLI
#!/bin/bash
# ...
# Проверьте статус; повторяйте, пока processing_status не станет "ended"
ant messages:batches retrieve \
--message-batch-id "$MESSAGE_BATCH_ID" \
--transform processing_status --raw-output
```
```python Python
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
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)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
let messageBatch;
while (true) {
messageBatch = await client.messages.batches.retrieve(messageBatchId);
if (messageBatch.processing_status === "ended") {
break;
}
console.log(`Batch ${messageBatchId} is still processing... waiting`);
await new Promise((resolve) => setTimeout(resolve, 60_000));
}
console.log(messageBatch);
```
```csharp C#
AnthropicClient client = new();
string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");
MessageBatch messageBatch = null;
while (true)
{
messageBatch = await client.Messages.Batches.Retrieve(messageBatchId);
if (messageBatch.ProcessingStatus == "ended")
{
break;
}
Console.WriteLine($"Batch {messageBatchId} is still processing...");
await Task.Delay(60000);
}
Console.WriteLine(messageBatch);
```
```go Go
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
var messageBatch *anthropic.MessageBatch
for {
var err error
messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID, anthropic.MessageBatchGetParams{})
if err != nil {
log.Fatal(err)
}
if messageBatch.ProcessingStatus == "ended" {
break
}
fmt.Printf("Batch %s is still processing...\n", messageBatchID)
time.Sleep(60 * time.Second)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.batches.MessageBatch;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
MessageBatch messageBatch = null;
while (true) {
messageBatch = client.messages().batches().retrieve(messageBatchId);
if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) {
break;
}
System.out.println("Batch " + messageBatchId + " is still processing...");
Thread.sleep(60000);
}
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$messageBatchId = getenv("MESSAGE_BATCH_ID");
$messageBatch = null;
while (true) {
$messageBatch = $client->messages->batches->retrieve(
messageBatchID: $messageBatchId,
);
if ($messageBatch->processingStatus === "ended") {
break;
}
echo "Batch {$messageBatchId} is still processing...\n";
sleep(60);
}
echo json_encode($messageBatch, JSON_PRETTY_PRINT);
```
```ruby Ruby
client = Anthropic::Client.new
message_batch_id = ENV["MESSAGE_BATCH_ID"]
message_batch = nil
loop do
message_batch = client.messages.batches.retrieve(message_batch_id)
break if message_batch.processing_status == :ended
puts "Batch #{message_batch_id} is still processing..."
sleep 60
end
puts message_batch
```
### Получение списка всех Message Batches
Вы можете получить список всех Message Batches в вашем рабочем пространстве с помощью [эндпоинта списка](https://platform.claude.com/docs/ru/api/messages/batches/list). API поддерживает пагинацию, автоматически загружая дополнительные страницы по мере необходимости:
```bash cURL
#!/bin/sh
# Получает одну страницу. Пока has_more в ответе равно true, передавайте его
# last_id как after_id для получения следующей страницы. (SDK и CLI
# выполняют автоматическую пагинацию.)
curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"
```
```bash CLI
# Автоматически загружает дополнительные страницы по мере необходимости
ant messages:batches list --limit 20
```
```python Python
client = anthropic.Anthropic()
# Автоматически загружает дополнительные страницы по мере необходимости.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
// Автоматически загружает дополнительные страницы по мере необходимости.
for await (const messageBatch of client.messages.batches.list({
limit: 20
})) {
console.log(messageBatch);
}
```
```csharp C#
AnthropicClient client = new();
var parameters = new BatchListParams
{
Limit = 20
};
// Автоматически загружает дополнительные страницы по мере необходимости
var page = await client.Messages.Batches.List(parameters);
await foreach (var messageBatch in page.Paginate())
{
Console.WriteLine(messageBatch);
}
```
```go Go
client := anthropic.NewClient()
// Автоматически загружает дополнительные страницы по мере необходимости
iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
Limit: anthropic.Int(20),
})
for iter.Next() {
messageBatch := iter.Current()
fmt.Println(messageBatch)
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Автоматически загружает дополнительные страницы по мере необходимости
for (MessageBatch messageBatch : client
.messages()
.batches()
.list(BatchListParams.builder().limit(20).build())
.autoPager()) {
System.out.println(messageBatch);
}
```
```php PHP
$client = new Client();
// Автоматически загружает дополнительные страницы по мере необходимости
foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
echo $messageBatch->id . "\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Автоматически загружает дополнительные страницы по мере необходимости
client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
puts message_batch
end
```
### Получение результатов пакета
После завершения обработки пакета каждый запрос Messages в пакете имеет результат. Существует четыре типа результатов:
| Тип результата | Описание |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `succeeded` | Запрос выполнен успешно. Включает результат сообщения. |
| `errored` | При выполнении запроса произошла ошибка, и сообщение не было создано. Возможные ошибки включают недопустимые запросы и внутренние ошибки сервера. Плата за эти запросы не взимается. |
| `canceled` | Пользователь отменил пакет до того, как этот запрос мог быть отправлен модели. Плата за эти запросы не взимается. |
| `expired` | Пакет достиг 24-часового срока истечения до того, как этот запрос мог быть отправлен модели. Плата за эти запросы не взимается. |
Поле `request_counts` пакета показывает обзор ваших результатов, указывая, сколько запросов достигло каждого из этих четырёх состояний.
Результаты пакета доступны для загрузки по свойству `results_url` в Message Batch, а также, если позволяют разрешения организации, в Console. Из-за потенциально большого размера результатов рекомендуется [получать результаты потоковой передачей](https://platform.claude.com/docs/ru/api/messages/batches/results), а не загружать их все сразу.
```bash cURL
#!/bin/sh
# Получите results_url пакета, затем потоково читайте результаты .jsonl,
# на которые он указывает. Для обработки отдельных результатов (повторы, ошибки валидации)
# используйте примеры SDK на других вкладках.
RESULTS_URL=$(curl -s "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| jq -r '.results_url')
curl -s "$RESULTS_URL" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| jq -r '"\(.result.type): \(.custom_id)"'
```
```bash CLI
# Выводит по одной строке на результат, напр. `{"custom_id":"test-1","type":"succeeded",…}`.
# Для обработки отдельных результатов (повторы, ошибки валидации) используйте примеры SDK
# на других вкладках.
ant messages:batches results \
--message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
--transform '{custom_id,"type":result.type,"error":result.error.error.type}' \
--format jsonl
```
```python Python
client = anthropic.Anthropic()
# Потоково считываем файл результатов экономными по памяти частями, обрабатывая их по одной
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
outcome = result.result
match outcome.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if outcome.error.error.type == "invalid_request_error":
# Перед повторной отправкой запроса необходимо исправить тело запроса
print(f"Validation error {result.custom_id}")
else:
# Запрос можно повторить напрямую
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")
```
```typescript TypeScript
const client = new Anthropic();
// Потоковая передача файла результатов экономными по памяти частями, обработка по одной за раз
for await (const result of await client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
)) {
switch (result.result.type) {
case "succeeded":
console.log(`Success! ${result.custom_id}`);
break;
case "errored":
if (result.result.error.type === "invalid_request_error") {
// Тело запроса необходимо исправить перед повторной отправкой
console.log(`Validation error: ${result.custom_id}`);
} else {
// Запрос можно повторить напрямую
console.log(`Server error: ${result.custom_id}`);
}
break;
case "expired":
console.log(`Request expired: ${result.custom_id}`);
break;
}
}
```
```csharp C#
AnthropicClient client = new();
await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"))
{
switch (result.Result.Type)
{
case "succeeded":
Console.WriteLine($"Success! {result.CustomID}");
break;
case "errored":
if (result.Result.Error?.Type == "invalid_request")
{
Console.WriteLine($"Validation error: {result.CustomID}");
}
else
{
Console.WriteLine($"Server error: {result.CustomID}");
}
break;
case "expired":
Console.WriteLine($"Request expired: {result.CustomID}");
break;
}
}
```
```go Go
client := anthropic.NewClient()
stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", anthropic.MessageBatchResultsParams{})
for stream.Next() {
result := stream.Current()
switch variant := result.Result.AsAny().(type) {
case anthropic.MessageBatchSucceededResult:
fmt.Printf("Success! %s\n", result.CustomID)
case anthropic.MessageBatchErroredResult:
fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message)
case anthropic.MessageBatchExpiredResult:
fmt.Printf("Request expired: %s\n", result.CustomID)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.batches.BatchResultsParams;
import com.anthropic.models.messages.batches.MessageBatchIndividualResponse;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Потоково читаем файл результатов экономными по памяти фрагментами, обрабатывая их по одному
try (
StreamResponse streamResponse = client
.messages()
.batches()
.resultsStreaming(
BatchResultsParams.builder()
.messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")
.build()
)
) {
streamResponse
.stream()
.forEach(result -> {
switch (result.result().type().value()) {
case SUCCEEDED -> System.out.println("Success! " + result.customId());
case ERRORED -> {
if (result.result().asErrored().error().error().isInvalidRequestError()) {
// Перед повторной отправкой запроса необходимо исправить его тело
System.out.println("Validation error: " + result.customId());
} else {
// Запрос можно повторить напрямую
System.out.println("Server error: " + result.customId());
}
}
case EXPIRED -> System.out.println("Request expired: " + result.customId());
}
});
}
```
```php PHP
use Anthropic\Messages\Batches\MessageBatchErroredResult;
use Anthropic\Messages\Batches\MessageBatchExpiredResult;
use Anthropic\Messages\Batches\MessageBatchSucceededResult;
$client = new Client();
foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) {
switch (true) {
case $result->result instanceof MessageBatchSucceededResult:
echo "Success! {$result->customID}\n";
break;
case $result->result instanceof MessageBatchErroredResult:
if ($result->result->error->error->type === "invalid_request_error") {
echo "Validation error: {$result->customID}\n";
} else {
echo "Server error: {$result->customID}\n";
}
break;
case $result->result instanceof MessageBatchExpiredResult:
echo "Request expired: {$result->customID}\n";
break;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result|
outcome = result.result
case outcome
when Anthropic::Models::Messages::MessageBatchSucceededResult
puts "Success! #{result.custom_id}"
when Anthropic::Models::Messages::MessageBatchErroredResult
if outcome.error.type == :invalid_request
puts "Validation error: #{result.custom_id}"
else
puts "Server error: #{result.custom_id}"
end
when Anthropic::Models::Messages::MessageBatchExpiredResult
puts "Request expired: #{result.custom_id}"
end
end
```
Результаты представлены в формате `.jsonl`, где каждая строка является валидным JSON-объектом, представляющим результат одного запроса в Message Batch. Для каждого полученного результата вы можете выполнять различные действия в зависимости от его `custom_id` и типа результата. Вот пример набора результатов:
```jsonl .jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","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-5-5","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` будет иметь стандартную [структуру ошибки](https://platform.claude.com/docs/ru/api/errors#error-shapes).
**Порядок результатов пакета может не совпадать с порядком входных данных**
Результаты пакета могут возвращаться в любом порядке и могут не соответствовать порядку запросов при создании пакета. В приведённом выше примере результат второго запроса пакета возвращается раньше первого. Чтобы правильно сопоставить результаты с соответствующими запросами, всегда используйте поле `custom_id`.
### Отмена Message Batch
Вы можете отменить Message Batch, который в данный момент обрабатывается, с помощью [эндпоинта отмены](https://platform.claude.com/docs/ru/api/messages/batches/cancel). Сразу после отмены `processing_status` пакета будет `canceling`. Вы можете использовать ту же технику опроса, описанную ранее, чтобы дождаться завершения отмены. Отменённые пакеты получают статус `ended` и могут содержать частичные результаты для запросов, обработанных до отмены.
```bash cURL
#!/bin/sh
# ...
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"
```
```bash CLI
#!/bin/bash
# ...
ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID"
```
```python Python
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.cancel(MESSAGE_BATCH_ID);
console.log(messageBatch);
```
```csharp C#
AnthropicClient client = new();
string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");
var messageBatch = await client.Messages.Batches.Cancel(messageBatchId);
Console.WriteLine(messageBatch);
```
```go Go
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID, anthropic.MessageBatchCancelParams{})
if err != nil {
log.Fatal(err)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.batches.*;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageBatch messageBatch = client
.messages()
.batches()
.cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d");
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$messageBatch = $client->messages->batches->cancel(
messageBatchID: 'msgbatch_example_id',
);
echo $messageBatch;
```
```ruby Ruby
client = Anthropic::Client.new
message_batch_id = ENV.fetch("MESSAGE_BATCH_ID")
message_batch = client.messages.batches.cancel(message_batch_id)
puts message_batch
```
Ответ показывает пакет в состоянии `canceling`:
```json Output
{
"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
Message Batches API поддерживает «prompt caching» (кэширование подсказок), что позволяет потенциально снизить затраты и время обработки пакетных запросов. Скидки от кэширования подсказок и Message Batches могут суммироваться, обеспечивая ещё большую экономию при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш обеспечиваются по принципу «best effort». Пользователи обычно наблюдают частоту попаданий в кэш от 30% до 98% в зависимости от характера их трафика.
Чтобы максимизировать вероятность попаданий в кэш в пакетных запросах:
1. Включайте идентичные блоки `cache_control` в каждый запрос Message в вашем пакете.
2. Поддерживайте стабильный поток запросов, чтобы записи кэша не истекали по окончании их 5-минутного срока жизни.
3. Структурируйте запросы так, чтобы они разделяли как можно больше кэшированного контента.
Пример реализации кэширования подсказок в пакете:
```bash 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": "my-first-request",
"params": {
"model": "claude-opus-5-5",
"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": "",
"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-5-5",
"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": "",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Write a summary of Pride and Prejudice."}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-5-5
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.
- type: text
text: ""
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-5-5
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.
- type: text
text: ""
cache_control:
type: ephemeral
messages:
- role: user
content: Write a summary of Pride and Prejudice.
YAML
```
```python Python
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="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
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": "",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
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": "",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Write a summary of Pride and Prejudice.",
}
],
),
),
]
)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5-5",
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: "",
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-5-5",
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: "",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }]
}
}
]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new List
{
new()
{
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"
},
new()
{
Text = "",
CacheControl = new()
}
},
Messages =
[
new() { Role = Role.User, Content = "Analyze the major themes in Pride and Prejudice." }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new List
{
new()
{
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"
},
new()
{
Text = "",
CacheControl = new()
}
},
Messages =
[
new() { Role = Role.User, Content = "Write a summary of Pride and Prejudice." }
]
}
}
]
});
```
```go Go
client := anthropic.NewClient()
messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
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",
},
{
Text: "",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
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",
},
{
Text: "",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")),
},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
import com.anthropic.models.messages.batches.*;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams createParams = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.build(),
TextBlockParam.builder()
.text("")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Analyze the major themes in Pride and Prejudice.")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.build(),
TextBlockParam.builder()
.text("")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Write a summary of Pride and Prejudice.")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(createParams);
```
```php PHP
$client = new Client();
$messageBatch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-5-5',
'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' => '',
'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-5-5',
'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' => '',
'cache_control' => ['type' => 'ephemeral']
]
],
'messages' => [
['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.']
]
]
]
],
);
```
```ruby Ruby
client = Anthropic::Client.new
message_batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5-5",
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: "",
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-5-5",
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: "",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Write a summary of Pride and Prejudice." }
]
}
}
]
)
```
В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст «Гордости и предубеждения», помеченный `cache_control`, чтобы повысить вероятность попаданий в кэш.
### Серверные инструменты и агентный цикл
Все [серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, advisor и поиск инструментов) работают в пакетных запросах. Обработчик пакетов выполняет тот же серверный агентный цикл, что и синхронный Messages API.
Поскольку нет открытого соединения, которое нужно поддерживать, пакетный цикл выполняет **больше итераций за ход**, чем синхронный запрос, прежде чем вернуть `stop_reason: "pause_turn"`. Если результат пакета возвращается с `pause_turn`, ход не завершился; вы можете продолжить его, отправив приостановленное содержимое ассистента в последующем запросе (пакетном или синхронном) точно так, как показано в [паттерне продолжения pause\_turn](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).
Обработчик пакетов дополнительно ограничивает `web_search` для каждой организации, чтобы высокопараллельная пакетная обработка не исчерпала ограничение скорости веб-поиска вашей организации. Пакет автоматически повторяет ограниченные запросы; вам не нужно обрабатывать это самостоятельно, но очень большие пакеты с веб-поиском могут выполняться дольше.
### Расширенный вывод (бета)
Бета-заголовок `output-300k-2026-03-24` повышает предел `max_tokens` до 300 000 для пакетных запросов, использующих Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, а также Claude Haiku 5.5. Добавьте этот заголовок, чтобы генерировать за один ход выходные данные, значительно превышающие стандартный лимит `max_tokens` в 128k.
Расширенный вывод доступен только в Message Batches API, а не в синхронном Messages API. Он поддерживается в Claude API и Claude Platform на AWS и в настоящее время недоступен в Amazon Bedrock, Google Cloud или Microsoft Foundry.
Используйте расширенный вывод для генерации длинных текстов, таких как черновики объёмом с книгу и техническая документация, исчерпывающее извлечение структурированных данных, крупные каркасы генерации кода и длинные цепочки рассуждений.
Одна генерация на 300k токенов может занять более часа, поэтому планируйте отправку пакетов с учётом 24-часового окна обработки. Применяются стандартные цены пакетной обработки (50% от стандартных цен API).
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: output-300k-2026-03-24" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "long-form-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 300000,
"messages": [
{"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
]
}
}
]
}'
```
```bash CLI
ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML'
requests:
- custom_id: long-form-request
params:
model: claude-opus-5-5
max_tokens: 300000
messages:
- role: user
content: >-
Write a comprehensive technical guide to building distributed
systems, covering architecture patterns, consistency models,
fault tolerance, and operational best practices.
YAML
```
```python Python
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.beta.messages.batches.create({
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: "claude-opus-5-5",
max_tokens: 300000,
messages: [
{
role: "user",
content:
"Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."
}
]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Anthropic.Models.Beta.Messages.Batches;
using Model = Anthropic.Models.Messages.Model;
AnthropicClient client = new();
var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams
{
Betas = ["output-300k-2026-03-24"],
Requests =
[
new()
{
CustomID = "long-form-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 300_000,
Messages =
[
new() { Role = Role.User, Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go
client := anthropic.NewClient()
batch, err := client.Beta.Messages.Batches.New(context.Background(),
anthropic.BetaMessageBatchNewParams{
Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"},
Requests: []anthropic.BetaMessageBatchNewParamsRequest{
{
CustomID: "long-form-request",
Params: anthropic.BetaMessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 300_000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."),
),
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(batch.ID)
```
```java Java
import com.anthropic.models.beta.messages.batches.*;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addBeta("output-300k-2026-03-24")
.addRequest(
BatchCreateParams.Request.builder()
.customId("long-form-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(300_000L)
.addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.")
.build()
)
.build()
)
.build();
BetaMessageBatch messageBatch = client.beta().messages().batches().create(params);
IO.println(messageBatch);
}
```
```php PHP
$client = new Client();
$batch = $client->beta->messages->batches->create(
betas: ['output-300k-2026-03-24'],
requests: [
[
'custom_id' => 'long-form-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 300_000,
'messages' => [
['role' => 'user', 'content' => 'Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.']
]
]
]
],
);
echo $batch->id;
```
```ruby Ruby
client = Anthropic::Client.new
batch = client.beta.messages.batches.create(
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: "claude-opus-5-5",
max_tokens: 300_000,
messages: [
{ role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
)
puts batch
```
### Лучшие практики эффективной пакетной обработки
Чтобы получить максимум от Batches API:
* Регулярно отслеживайте статус обработки пакетов и реализуйте соответствующую логику повторных попыток для неудавшихся запросов.
* Используйте осмысленные значения `custom_id`, чтобы легко сопоставлять результаты с запросами, поскольку порядок не гарантируется.
* Рассмотрите разбиение очень больших наборов данных на несколько пакетов для лучшей управляемости.
* Выполните пробный запуск одной структуры запроса с помощью Messages API, чтобы избежать ошибок валидации.
### Устранение распространённых проблем
При неожиданном поведении:
* Убедитесь, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком велик, вы можете получить ошибку 413 `request_too_large`.
* Проверьте, что вы используете [поддерживаемые модели](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#supported-models) для всех запросов в пакете.
* Убедитесь, что каждый запрос в пакете имеет уникальный `custom_id`.
* Убедитесь, что прошло менее 29 дней с момента `created_at` пакета (а не `ended_at` обработки). Если прошло более 29 дней, результаты больше не будут доступны для просмотра.
* Убедитесь, что пакет не был отменён.
Обратите внимание, что сбой одного запроса в пакете не влияет на обработку других запросов.
## Хранение пакетов и конфиденциальность
* **Изоляция рабочих пространств**: пакеты изолированы в рабочем пространстве, в котором они созданы. Доступ к ним возможен только через запросы API в том же рабочем пространстве или для пользователей с разрешением на просмотр пакетов рабочего пространства в Console.
* **Доступность результатов**: результаты пакета доступны в течение 29 дней после создания пакета, что даёт достаточно времени для получения и обработки.
## Хранение данных
Пакетная обработка хранит данные запросов и ответов до 29 дней после создания пакета. Вы можете удалить пакет сообщений в любое время после обработки с помощью эндпоинта `DELETE /v1/messages/batches/{batch_id}`. Чтобы удалить пакет, находящийся в обработке, сначала отмените его. Асинхронная обработка требует хранения на стороне сервера как входных, так и выходных данных до завершения пакета и получения результатов.
Информацию о соответствии требованиям ZDR для всех функций см. в разделе [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
## Часто задаваемые вопросы
Обработка пакетов может занимать до 24 часов, но многие завершаются раньше. Фактическое время обработки зависит от размера пакета, текущего спроса и объёма ваших запросов. Возможно, что срок действия пакета истечёт и он не будет завершён в течение 24 часов.
Список поддерживаемых моделей см. в разделе [Поддерживаемые модели](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#supported-models).
Да, Message Batches API поддерживает почти все функции, доступные в Messages API, включая большинство бета-функций. Небольшое количество параметров (`stream`, `speed` и `max_tokens: 0`) не поддерживается. Полный список см. в разделе [Что можно включить в пакет](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#what-can-be-batched).
Message Batches API предлагает скидку 50% на всё использование по сравнению со стандартными ценами API. Это относится к входным токенам, выходным токенам и любым специальным токенам. Подробнее о ценах см. на странице [Цены](https://claude.com/pricing#anthropic-api).
Нет, после отправки пакет нельзя изменить. Если вам нужно внести изменения, следует отменить текущий пакет и отправить новый. Обратите внимание, что отмена может не вступить в силу немедленно.
Message Batches API имеет ограничения скорости на основе HTTP-запросов в дополнение к ограничениям на количество запросов, ожидающих обработки. См. [ограничения скорости Message Batches API](https://platform.claude.com/docs/ru/api/rate-limits#message-batches-api). Использование Batches API не влияет на ограничения скорости в Messages API.
При получении результатов каждый запрос имеет поле `result`, указывающее, был ли он `succeeded`, `errored`, `canceled` или `expired`. Для результатов `errored` предоставляется дополнительная информация об ошибке. Объект ответа с ошибкой см. в [справочнике API](https://platform.claude.com/docs/ru/api/messages/batches/create).
Message Batches API разработан с надёжными мерами конфиденциальности и разделения данных:
1. Пакеты и их результаты изолированы в рабочем пространстве, в котором они были созданы. Это означает, что доступ к ним возможен только через запросы API в том же рабочем пространстве.
2. Каждый запрос в пакете обрабатывается независимо, без утечки данных между запросами.
3. Результаты доступны только в течение ограниченного времени (29 дней) и подчиняются [политике хранения данных](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) Anthropic.
4. Загрузку результатов пакетов в Console можно отключить на уровне организации или для отдельных рабочих пространств.
Да, кэширование подсказок можно использовать с Message Batches API. Однако, поскольку асинхронные пакетные запросы могут обрабатываться параллельно и в любом порядке, попадания в кэш обеспечиваются по принципу «best effort».
## Следующие шаги
Включите естественные цитаты для RAG-приложений, предоставляя результаты поиска с указанием источников.
Снизьте затраты и задержку, кэшируя префиксы подсказок, общие для запросов в пакете.