# Claude Message Threads API: как работают треды

> Треды сообщений в Claude API: заголовок beta, запросы create и continue, поля, которые нужно отправлять снова, срок жизни и что делать после 404.

- Canonical HTML: https://omniakey.com/ru/blog/claude-message-threads-api-guide
- Markdown: https://omniakey.com/ru/blog/claude-message-threads-api-guide.md
- Published: 2026-11-04 (updated 2026-11-04)
- Author: Kiki, COO at OmniaKey
- Language: ru
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

Claude message threads API позволяет отправить длинный диалог один раз, а в каждом следующем ходу передавать только новые сообщения. Добавьте `"thread": {"type": "create"}` в первый запрос Messages и заголовок beta `message-threads-2026-08-12`: API держит диалог в памяти, и следующий запрос отправляет меньше (страница Message threads у Anthropic, 4 ноября 2026).

Это beta на всех моделях. Ею могут пользоваться 17 ID моделей, включая [Claude Opus 5.5](https://omniakey.com/ru/claude-opus-5-5), который вызывает код ниже. Заголовок beta нужен в каждом запросе треда.

## Что экономит тред

Без треда каждый ход несёт всю переписку: системный промпт, описания инструментов, все прошлые сообщения и все результаты инструментов. Тред хранит этот диалог вместе с ответом Claude под `id` ответа, а запрос continue отправляет только то, что произошло после (страница Message threads, 4 ноября 2026). Меньше данных на каждый ход.

Кэш промптов помогает тому же диалогу иначе. Попадание в кэш удешевляет повторяющийся ввод: на Opus 5.5 это 0,20 USD за миллион токенов против 4 USD за новый ввод (страница цен Anthropic, 4 ноября 2026). Запрос всё равно несёт этот ввод. Тред сокращает то, что вы отправляете; кэш снижает цену повторяющегося. Длинным сессиям нужно и то и другое, а [сокращение расхода токенов Claude Code](https://omniakey.com/ru/blog/reduce-claude-code-token-usage) разбирает сторону контекста.

Треды не меняют ни цены, ни лимиты скорости (страница Message threads, 4 ноября 2026). Актуальные тарифы — на странице [цены](https://omniakey.com/ru/pricing).

Кэш вы включаете сами. Отправляйте `cache_control` верхнего уровня в каждом запросе, и API применит его к последнему кэшируемому блоку `messages` этого запроса. Ограничение в четыре точки останова — общее правило кэша промптов для всей платформы, и автоматический кэш занимает одну из четырёх (страница кэша промптов Anthropic, 4 ноября 2026). Распределяйте так:

1. `cache_control` верхнего уровня, одна точка в каждом запросе треда;
2. одна на `system`, отправляется с запросом create;
3. одна на `tools`, тоже при create;
4. одна на самом новом сообщении.

Точки останова на ранее сохранённых сообщениях не входят в этот лимит: запрос continue отправляет только новые сообщения. Отправленная точка остаётся на месте. При повторной отправке диалога уберите точки с прошлых сообщений и оставьте одну на последнем блоке (страница Message threads, 4 ноября 2026).

## Первый ход и продолжение

Три шага:

1. Положите ключ Anthropic в `ANTHROPIC_API_KEY`.
2. Отправьте весь диалог, с `system` и `tools`, если пользуетесь ими, плюс `"thread": {"type": "create"}`.
3. Отправьте только сообщения после последнего ответа плюс `"thread": {"type": "continue", "previous_message_id": "<previous id>"}`, а `system` и `tools` не передавайте.

Каждый запрос несёт заголовок beta и `anthropic-version: 2026-10-21`, текущую версию (страница версий API Anthropic, 4 ноября 2026).

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'
```

Сохраните `id` из этого ответа. Следующий запрос отправит только новое сообщение:

```bash
PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON
```

Храните самый свежий `id` каждого ответа: тред только дополняется, каждый `id` ответа можно продолжить один раз, а следующий запрос должен использовать последний (страница Message threads, 4 ноября 2026).

Если нужен другой способ получить ключ API, OmniaKey продаёт доступ к API Claude с теми же ID моделей, так что тело запроса не меняется. Треды — beta на стороне Anthropic, поэтому перед работой в продакшене проверьте, что ваш посредник передаёт поле `thread` без изменений.

Python SDK ведёт id за вас. Соберите помощник через `client.beta.messages.thread(...)`, который только готовит вызов, и отправляйте каждый ход через `thread.send()`. Помощник добавляет заголовок beta, создаёт тред на первом ходу, продолжает только с новыми сообщениями и один раз отправляет весь диалог заново в новом запросе create, когда continue возвращает `thread_not_found`, `thread_already_continued` или `thread_continue_in_flight` (страница Message threads, 4 ноября 2026).

```python
import anthropic

client = anthropic.Anthropic()  # читает ANTHROPIC_API_KEY

# Помощник пока ничего не отправляет; он хранит поля, которые повторяются каждый ход.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # в следующий раз продолжайте с этого id
```

Мы не запускали эти запросы против API Anthropic; форма запросов взята со страницы Message threads. Для потоковой передачи `thread.stream(...)` и `stream.get_final_message()` дают тот же ход, а `thread.previous_message_id` возвращает id, если вы предпочитаете вести его сами.

## Что отправлять снова, а что никогда

Фиксированные поля отправляйте с одними и теми же значениями в каждом запросе, `system` и `tools` — только в запросе create, а свободные поля могут меняться от хода к ходу.

|Группа|Поля|Правило|
|-|-|-|
|Только create|`system`, `tools`|Только в запросе create; если передать любое из них в запросе continue, даже как `null`, вернётся 400.|
|Фиксированные|`model`, `tool_choice`, `thinking`, `mcp_servers` кроме токена авторизации каждого сервера, `context_management`, `output_config`, `skills` в `container`, `cache_control` верхнего уровня и набор значений `anthropic-beta`|Одно и то же значение каждый раз. Другое значение вернёт 400 и назовёт отличающееся поле.|
|Свободные|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` и поля без имени|Меняйте когда угодно.|

400 на изменённое фиксированное поле несёт `thread_fingerprint_mismatch`, а в сообщении перечислены отличающиеся поля. Чтобы изменить такое значение, начните новый тред с полным диалогом и новым значением.

Если пропустить `previous_message_id`, continue вернёт 400, в теле будет message, но не будет `error_code`; то же самое при `system` или `tools`. Запрос continue должен нести ровно сообщения после последнего ответа.

`mcp_servers` фиксировано, но URL серверов и токены авторизации живут только в вашем запросе, поэтому отправляйте список в каждом запросе с MCP; токен может смениться между запросами. `id` контейнера тоже живёт только в вашем запросе, поэтому `container` отправляйте каждый раз (страница Message threads, 4 ноября 2026).

Серверный fallback решается при create: отправляйте `fallbacks` в каждом запросе треда или ни в одном. Значение может меняться между ходами, но добавление или удаление поля вернёт `thread_fingerprint_mismatch`.

## Срок жизни, повторная отправка и 404

Тред истекает через 5 минут после последнего запроса, а API удаляет его не позже чем через 1 час после последнего использования. Каждый сохранённый ответ заново запускает эти 5 минут. Треды не подходят для нулевого хранения данных: диалог, системный промпт и инструменты лежат в памяти в зашифрованном виде и никогда не пишутся в долговременное хранилище (страница Message threads, 4 ноября 2026).

Ни одно поле ответа не говорит, сохранила ли API ход — ни при create, ни при continue. Вы узнаёте это из следующего запроса continue, поэтому приложение остаётся источником истины и хранит собственную копию каждого сообщения (страница Message threads, 4 ноября 2026).

Когда continue возвращает 404 `thread_not_found`, отправьте весь диалог новым запросом create и продолжайте с `id` этого ответа. Тот же 404 приходит во всех этих случаях:

- тред истёк;
- прошлый ход был обслужен и затем отброшен, например вызов инструмента, обрезанный `max_tokens`;
- прошлый ответ написала fallback-модель;
- прошлый ответ ещё генерируется;
- запрос пришёл из другой организации, рабочего пространства, от другого пользователя или ключа рабочего пространства;
- новые сообщения добавляют содержимое, которого нет в сохранённом диалоге, например первое изображение в диалоге без изображений.

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

Потоковая передача добавляет правило: продолжайте с `id` ответа только после `message_stop`, потому что continue, отправленный раньше, может вернуть 404. Если поток запроса continue оборвался до `message_stop`, отправьте тот же запрос continue снова, а если вернётся `thread_already_continued` или `thread_continue_in_flight` — отправьте весь диалог заново. Оборванный поток помощник SDK оставляет вам на повтор.

Ещё три случая идут своим путём:

- `pause_turn`: продолжайте с `id` этого ответа с `"messages": []`. Если придёт 404, отправьте всё заново вместе с приостановленным ответом.
- `stop_reason: "refusal"`: начните новый тред без хода, который это вызвал; возможно, API уже хранит отклонённый ход.
- запись `fallback_message` в `usage.iterations` или в последнем `message_delta` потока отмечает ответ fallback: отправьте всё заново.

## Ошибки

Все пять ошибок треда приходят до запуска модели: запрос не тратит токены, а срок треда не меняется. `error.type` равен `invalid_request_error` для 400 и `not_found_error` для 404 (страница Message threads, 4 ноября 2026).

- **404, `thread_not_found`**: API не может продолжить этот тред. Отправьте весь диалог новым запросом create.
- **400, `thread_fingerprint_mismatch`**: фиксированное поле отличается от значения, сохранённого с тредом. Оставьте его прежним или начните новый тред.
- **400, `thread_already_continued`**: этот `id` ответа уже использован один раз. Продолжайте с самого свежего `id`, а если вы его не получили — отправьте всё заново.
- **400, `thread_continue_in_flight`**: continue с тем же `id` ещё выполняется, обычно это ваша прошлая попытка. Дайте ей завершиться или отправьте всё заново.
- **400, `thread_unsupported_request`**: запрос использует функцию или настройку организации, которых треды не поддерживают. `error.details.unsupported` называет одно из `context_management`, `cache_control`, `fallbacks`, `hipaa` или `inference_hooks`; список может расти, поэтому при незнакомом значении отправьте весь диалог без `thread`.

Message Batches не принимает поле `thread` (элемент пакета с ним падает с `invalid_request_error`), а подсчёт токенов и сжатие возвращают 400; также редактирование контекста, кроме `clear_thinking_20251015` с `keep: "all"`. Организации, готовые к HIPAA, и организации с включёнными Inference hooks исключены. Списка, чтения и удаления треда в API нет.

## Частые вопросы

### Что такое Claude Message Threads API?

Это beta-функция Messages API: она хранит диалог на стороне Anthropic, чтобы следующие ходы отправляли только новые сообщения. Заголовок beta — `message-threads-2026-08-12`, и каждый запрос добавляет объект `thread` с `type` равным `create` или `continue`.

### Работают ли треды с кэшем промптов?

Да. Тред не кэширует промпт за вас: отправляйте `cache_control` верхнего уровня в каждом запросе и держитесь четырёх точек останова. Точки на сохранённых сообщениях в этот счёт не входят; верхняя и точки на `system` или `tools` входят.

### Можно ли сменить модель посреди треда?

Смена модели требует нового треда. `model` — фиксированное поле, поэтому другое значение вернёт 400 `thread_fingerprint_mismatch`; начните новый тред с полным диалогом и новой моделью.

### Почему continue возвращает 400 без error\_code?

В continue нет `previous_message_id` или в нём есть `system` либо `tools`, даже как `null`. Такие 400 несут message и пропускают `error_code`, поэтому читайте текст.

### Сколько живёт тред и что происходит после истечения?

Тред истекает через 5 минут после последнего запроса и удаляется не позже чем через 1 час после последнего использования. После этого continue вернёт 404 `thread_not_found`; отправьте весь диалог новым запросом create и продолжайте с его `id`.

## Проверенные источники

- [Anthropic: message threads](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: кэш промптов](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: цены Claude API](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: версии API](https://platform.claude.com/docs/en/api/versioning)