Claude Platform Docs
СообщенияУправление контекстом

Ветки сообщений

Сократите время до первого токена для долго работающих агентов, особенно в длинных разговорах, отправляя в каждом запросе только новые сообщения.

С «message thread» (веткой сообщений) запросы становятся меньше, а «time to first token» (время до первого токена) остаётся ниже и стабильнее по мере роста разговора. Ветки приносят наибольшую пользу в длинных «agent loops» (агентных циклах). Без ветки каждый ход заново загружает весь разговор, и API заново проверяет и токенизирует его целиком. С веткой большая часть этой работы касается только нового хода.

«Message thread» (ветка сообщений) хранит разговор на сервере в течение короткого времени. Вы отправляете полный разговор один раз, вместе с системной подсказкой и инструментами. На каждом последующем ходе вы отправляете только новые сообщения и id предыдущего ответа. API восстанавливает разговор перед вызовом модели. Вы добавляете один параметр, thread, в запрос к Messages API. Ответ — это обычное сообщение.

Как работают ветки сообщений

  • Создание. Отправьте первый запрос так же, как вы делаете это сейчас, с полным диалогом, system и tools, и добавьте "thread": {"type": "create"}. API сохраняет диалог, включая ответ Claude, под id ответа.
  • Продолжение. Отправляйте только сообщения, появившиеся после предыдущего ответа, и добавьте "thread": {"type": "continue", "previous_message_id": "<previous id>"}. Не включайте system и tools в запрос. Ветка сохраняет значения из запроса на создание. Используйте id каждого нового ответа для следующего хода.
  • Повторная отправка. Ветка работает по принципу «best-effort» (без гарантий). Срок её действия истекает через 5 минут после последнего запроса, и API удаляет её не позднее чем через 1 час после последнего использования. Каждый ответ, который API сохраняет, перезапускает отсчёт этих 5 минут. Если API больше не может продолжить ветку, запрос на продолжение возвращает ошибку 404. Отправьте полный диалог снова в новом запросе на создание и продолжайте от id этого ответа. Вспомогательный объект ветки в SDK выполняет эту повторную отправку за вас (см. Поведение вспомогательного класса SDK). После ответа от резервной модели см. Использование резервных моделей с веткой.

Ваше приложение остаётся источником истины для разговора. Храните собственную копию каждого сообщения и с самого начала реализуйте путь повторного воспроизведения. Ни один ответ — ни на запрос создания, ни на запрос продолжения — не сообщает, сохранил ли API этот ход. Вы узнаёте об этом при следующем запросе продолжения. Вспомогательный объект ветки (thread helper) в SDK хранит эту копию в памяти, пока существует сам объект, и больше нигде её не сохраняет. Если разговор должен пережить ваш процесс, храните собственную копию.

Использование ветки с SDK

В SDK есть вспомогательный объект ветки, который формирует запросы ветки за вас. Создайте его с теми же полями, что и запрос Messages, а затем отправляйте по одному ходу за раз. Вспомогательный объект хранит полный диалог в памяти.

В этом примере два хода. Вспомогательный класс создаёт ветку на первом ходе и продолжает её на втором, а также добавляет бета-заголовок за вас. Верхнеуровневый cache_control необязателен. Он запрашивает «prompt caching» (кэширование подсказок) на каждом ходе (см. Кэширование подсказок в ветке). Без него каждый последующий ход по-прежнему отправляет только новые сообщения, но ничего не кэшируется, если вы сами не добавите точки останова кэша.

client = anthropic.Anthropic()

# Создаём вспомогательный объект. Этот вызов не отправляет запрос.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)

# Ход 1: вспомогательный объект создаёт поток и отправляет весь диалог
thread.send({"role": "user", "content": "Hi! I have a question about an order."})

# Ход 2: вспомогательный объект продолжает поток и отправляет только новое сообщение
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

for block in second.content:
    if block.type == "text":
        print(block.text)

Самостоятельная отправка поля thread

Чтобы формировать запросы ветки самостоятельно, например с помощью cURL, CLI или обычного метода create в SDK, добавляйте поле thread в каждый запрос.

Отправляйте бета-заголовок message-threads-2026-08-12 в каждом запросе ветки.

Этот пример создаёт ветку на первом ходе и продолжает её на втором. Верхнеуровневый cache_control запрашивает кэширование подсказок на каждом ходе. Он вступает в силу, как только разговор становится длиннее минимальной кэшируемой длины.

client = anthropic.Anthropic()

# Ход 1: отправьте весь диалог и создайте поток (thread)
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
    messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
    thread={"type": "create"},
    betas=["message-threads-2026-08-12"],
)

# Ход 2: отправьте только новое сообщение и id ответа из хода 1.
# Не указывайте system и tools: поток сохраняет их.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

Что отправлять в каждом запросе

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

API не хранит URL-адреса серверов MCP, токены авторизации MCP и id контейнера. Отправляйте mcp_servers и container в каждом запросе, который их использует. Токен авторизации MCP может меняться между запросами.

Вспомогательный объект ветки в SDK не включает system и tools в запросы на продолжение за вас и повторно отправляет фиксированные поля на каждом ходе.

Если вы используете резервные модели на стороне сервера, отправляйте поле fallbacks либо в каждом запросе ветки, либо ни в одном. См. Использование резервных моделей с веткой.

Чтобы изменить поле, задаваемое только при создании, или фиксированное поле, начните новую ветку: отправьте полный разговор в запросе на создание с новыми значениями.

В Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 и Claude Haiku 5.5 изменение system или tools делает блоки thinking и redacted_thinking, уже имеющиеся в разговоре, недействительными, и запрос на создание может вернуть ошибку 400. Чтобы этого избежать, исключите все блоки thinking и redacted_thinking из разговора, который вы отправляете. Тогда модель отвечает без этих более ранних рассуждений. См. Что считается редактированием, Когда prefix_mismatch_behavior не задано и Что API делает с недействительным блоком.

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

Новые сообщения обычно начинаются с сообщения user: вашего следующего хода пользователя или блоков tool_result, отвечающих на tool_use в предыдущем ответе. Если ответ останавливается с stop_reason: "pause_turn", возобновите его запросом на продолжение от id этого ответа с пустым списком messages ("messages": []). Если этот запрос возвращает ошибку 404, повторно отправьте полный диалог, включая приостановленный ответ, в новом запросе на создание. Не отправляйте новое сообщение user, пока ход приостановлен: API его отклонит. При использовании вспомогательного объекта ветки в SDK вызовите send() без сообщений: вспомогательный объект отправит этот запрос и выполнит повторную отправку при ошибке 404.

Ветка допускает только добавление, и каждый id ответа можно продолжить один раз. Всегда продолжайте от последнего id ответа в ветке. Чтобы отредактировать более раннее сообщение или создать от него ответвление, начните новую ветку запросом на создание. Чтобы заменить более ранние ходы сводкой, см. Сжатие разговора.

Кэширование подсказок в ветке

Ветка не кэширует вашу подсказку за вас. Кэширование подсказок работает так же, как без ветки: вы сами выбираете, где размещать точки останова кэша.

Чтобы кэшировать каждый ход, отправляйте верхнеуровневый cache_control в каждом запросе ветки, как в предыдущем примере. API применяет его к последнему кэшируемому блоку в messages каждого запроса. Затем каждый ход читает более ранний разговор из кэша и записывает в него новый ход. Верхнеуровневый cache_control — фиксированное поле: отправляйте одно и то же значение в каждом запросе.

Вы также можете самостоятельно размещать точки останова cache_control на блоках:

  • Точки останова, которые вы отправляете в запросе на создание, продолжают действовать на каждом последующем ходе, если они находятся в tools, в system или в блоке сообщения перед последним. Точка останова в последнем блоке messages запроса записывает кэш в этом запросе. Чтобы кэшировать каждый новый ход, отправляйте точку останова в каждом запросе. Запрос без точки останова всё равно может прочитать часть разговора из кэша.
  • Вы не можете переместить или удалить точку останова после её отправки, поскольку запрос продолжения не может повторно отправить более раннее сообщение.
  • Запрос с thread может содержать не более 4 точек останова cache_control. Верхнеуровневый cache_control считается за одну. Точки останова в system и tools запроса создания учитываются повторно в каждом запросе продолжения. Точки останова в более ранних сохранённых сообщениях не учитываются. Превышение лимита хотя бы на одну точку останова возвращает ошибку 400 с кодом thread_unsupported_request.
  • Если вы сами размещаете точки останова в блоках сообщений, удалите их из более ранних сообщений при повторном воспроизведении разговора в новом запросе создания и оставьте одну в последнем блоке, чтобы запрос не превышал лимит в 4 точки.

Потоковая передача

Ветки работают с потоковой передачей. id ответа приходит в событии message_start, но продолжайте от него только после получения события message_stop. Запрос на продолжение, отправленный раньше, может вернуть ошибку 404.

Если поток запроса на продолжение обрывается до message_stop, отправьте тот же запрос на продолжение снова. Если этот запрос возвращает ошибку thread_already_continued или thread_continue_in_flight, повторно отправьте полный разговор в новом запросе на создание.

Ваше соединение могло оборваться, пока сервер ещё генерировал ответ, или после того, как сервер его сохранил. Поэтому API может отклонить повторную попытку. Повторная отправка всегда безопасна.

Вспомогательный объект ветки в SDK не повторяет запрос на продолжение после прерванной потоковой передачи. См. Поведение вспомогательного класса SDK.

Восстановление, когда ветку нельзя продолжить

Запрос на продолжение возвращает ошибку 404 с error.details.error_code, равным thread_not_found, когда API не может продолжить ветку. Ответ не сообщает причину. Среди причин:

  • Срок действия ветки истёк.
  • API обслужил предыдущий ход, но не сохранил его. Например, API не сохраняет ответ, который заканчивается вызовом инструмента, обрезанным из-за max_tokens.
  • Предыдущий ответ написала резервная модель. См. Использование резервных моделей с веткой.
  • Предыдущий ответ всё ещё генерируется.
  • Запрос поступает из другой организации или рабочего пространства.
  • Запрос поступает от другого пользователя или сервисного аккаунта, а не от того, который создал ветку. Ветка, созданная с ключом рабочего пространства (устаревшим), остаётся привязанной к этому ключу, поэтому используйте один и тот же ключ для всей ветки.
  • Новые сообщения добавляют то, что сохранённый разговор не может принять. Например, первое изображение в разговоре, где их не было, может вернуть эту ошибку.

Для восстановления отправьте весь разговор из вашей собственной копии в новом запросе на создание, с system и tools. Вспомогательный объект ветки в SDK сам отправляет этот запрос на создание один раз и при этом опускает точки останова cache_control предыдущих ходов. Если предыдущие сообщения в вашей копии содержат точки останова cache_control, сначала удалите их (см. Кэширование подсказок в ветке). Затем продолжайте с id нового ответа. Если предыдущий ответ написала резервная модель, см. Использование резервных моделей с веткой. Чтобы исключить причины, связанные с владением, используйте один и тот же ключ API и рабочее пространство для каждого запроса ветки. На Claude Platform on AWS подписывайте каждый запрос ветки учётными данными роли IAM или пользователя IAM, который её создал.

Запрос к несуществующей модели также возвращает ошибку 404, поэтому проверяйте error.details.error_code перед повторной отправкой.

Если запрос на продолжение по-прежнему возвращает ошибку 404 сразу после воспроизведения, возможно, API не может сохранить этот диалог, например очень большой. Отправьте его без thread. Вспомогательный объект ветки в SDK делает это, когда вы создаёте его с параметром unsupported_request_behavior, установленным в continue_unthreaded. В противном случае он выполняет воспроизведение на каждом ходе.

После отказа

Когда ответ содержит stop_reason: "refusal", не продолжайте ветку. API может уже хранить отклонённый ход, и запрос на продолжение не может его удалить. Начните новую ветку с запроса на создание, который опускает или перефразирует ход, приведший к отказу. См. Отказы и резервные модели. Вспомогательный объект ветки в SDK делает это за вас: он не сохраняет отклонённый ход, и его следующий ход начинает новую ветку.

Использование резервных моделей с веткой

Резервные модели на стороне сервера доступны с ветками в Claude API. Решите при создании ветки: отправлять fallbacks в каждом запросе ветки или ни в одном. Значение fallbacks может меняться между запросами. Запрос на продолжение, который добавляет или убирает fallbacks, возвращает ошибку 400 с кодом thread_fingerprint_mismatch.

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

  1. Если stop_reason равен "refusal", следуйте разделу После отказа.
  2. В противном случае найдите запись fallback_message в usage.iterations. При потоковой передаче считайте её из последнего события message_delta. Если такой записи нет, продолжайте ветку как обычно.
  3. Если она есть, ответ написала резервная модель. Отправьте весь разговор, включая этот ответ и ваше следующее сообщение, в новом запросе на создание. Сохраните в нём бета-заголовок server-side-fallback-2026-07-01. Выберите один из этих двух запросов:
    • Тот же запрос ещё раз. Оставьте model, fallbacks и другие параметры без изменений. Если ответит запрошенная вами модель, API сохранит новую ветку. Если ответит резервная модель, ответ снова будет содержать запись fallback_message, и API не сохранит его, поэтому повторите этот шаг на следующем ходе. Закреплённая маршрутизация может направлять эти запросы сразу к резервной модели, поэтому на каждом ходе может отправляться весь разговор. Вспомогательный объект ветки в SDK работает именно так.
    • Новая ветка на резервной модели. Установите model в значение model из этой записи fallback_message, опустите fallbacks и используйте параметры, которые принимает эта модель. API сразу сохраняет эту ветку, и она остаётся на резервной модели. Попытка с резервной моделью могла выполняться с настройками, отличными от отправленных вами, поэтому API может отклонить значения, скопированные из вашего первого запроса.
  4. Вернитесь к шагу 1 с ответом на этот запрос. Когда в нём нет записи fallback_message, продолжайте новую ветку с его id.

Закреплённая маршрутизация начинается после того, как запрос переключается на резервную модель (запрос на создание или запрос без thread). Примерно в течение часа она может направлять последующие запросы на создание для того же разговора, которые включают fallbacks, сразу к резервной модели, не пытаясь обратиться к запрошенной вами модели. API не сохраняет ни один из этих ходов, и каждый ход, получивший ответ, перезапускает отсчёт часа. Запрос на продолжение никогда не запускает эту маршрутизацию и никогда её не использует. Закреплённая маршрутизация не применяется, если ваша организация или рабочее пространство использует нулевое хранение данных или ключи шифрования, управляемые клиентом.

Сжатие разговора

Ветка допускает только добавление, поэтому вы не можете заменить её более ранние ходы сводкой. Чтобы сжать разговор, начните новую ветку со сводки. Напишите сводку в своём коде и отправьте её как обычное сообщение в новом запросе на создание, с system и tools. Сжатие по запросу недоступно с ветками (см. Функции, которые ветки не поддерживают).

Поведение вспомогательного класса SDK

Что вспомогательный класс делает за вас:

  • Добавляет бета-заголовок message-threads-2026-08-12 к каждому запросу, который использует ветку.
  • Создаёт ветку на первом ходе и затем продолжает её, отправляя только новые сообщения и опуская system и tools.
  • Один раз воспроизводит весь диалог в новом запросе на создание, когда запрос на продолжение возвращает thread_not_found, thread_already_continued или thread_continue_in_flight.
  • Возобновляет ответ pause_turn, когда вы вызываете send() без сообщений.
  • Начинает новую ветку после отказа. Вы получаете ответ stop_reason: "refusal" как обычно, но вспомогательный объект не сохраняет этот ход: он забирает обратно сообщения, которые вы передали в этот вызов. Сообщения, которые вы добавили с помощью thread.append(...) или передали при создании вспомогательного объекта, остаются подготовленными к отправке. Ваш следующий ход отправляет их вместе с диалогом, предшествовавшим отклонённому ходу, в новом запросе на создание. Отправьте перефразированное сообщение или, если к отказу привело подготовленное сообщение, начните новую ветку из params без него.
  • Отправляет новый запрос на создание после ответа от резервной модели. Когда ответ содержит запись fallback_message в usage.iterations, вспомогательный объект сохраняет ответ и на следующем ходе отправляет весь разговор в новом запросе на создание. Он не ждёт ошибки 404. Этот запрос сохраняет заданные вами model и fallbacks.
  • Опускает точки останова cache_control предыдущих ходов всякий раз, когда отправляет их повторно, например при воспроизведении или на первом ходе ответвления. Ваши новейшие сообщения, system, tools и cache_control верхнего уровня отправляются в том виде, в каком вы их передали.

Что вы обрабатываете сами:

  • Резервные модели. Пока API продолжает отвечать от резервной модели, вспомогательный объект на каждом ходе отправляет весь разговор в новом запросе на создание, поскольку API не сохраняет ни один из этих ходов. Он возвращается к запросам на продолжение после ответа от запрошенной вами модели. Чтобы вместо этого перевести разговор на резервную модель, начните новую ветку из params с этой model и без fallbacks, как описано в разделе Использование резервных моделей с веткой.
  • Прерванные потоки. Если поток обрывается посреди ответа, вспомогательный объект сохраняет завершённые блоки и весь полученный текст, а следующий ход отправляет весь диалог в новом запросе на создание. Вспомогательный объект не выполняет повторную попытку сам: чтобы вместо этого повторно отправить прерванный ход, вызовите send() без сообщений. Если сохранённая часть заканчивается вызовами инструментов, ответьте на них в следующем сообщении. Если вы прекращаете чтение потока после того, как он показал stop_reason: "refusal", вспомогательный объект считает этот ход отказом.
  • Другие ошибки. Ошибки thread_fingerprint_mismatch и thread_unsupported_request передаются в ваш код. Чтобы продолжить без thread после ошибки thread_unsupported_request, создайте вспомогательный объект с параметром unsupported_request_behavior, установленным в continue_unthreaded. С этой настройкой вспомогательный объект также прекращает использовать thread, когда первый запрос на продолжение после воспроизведения снова возвращает thread_not_found. Возможно, API не может сохранить этот диалог. Без этой настройки вспомогательный объект выполняет воспроизведение на каждом ходе. Средство запуска инструментов, которое создаёт собственную ветку, использует эту настройку по умолчанию.

Бета-версия средства запуска инструментов SDK также по умолчанию использует ветку, которую можно отключить при создании средства запуска.

Другие методы вспомогательного класса

Чтобы сделать этоИспользуйте
Выполнить ход с потоковой передачейthread.stream(...)
Готовый ответ хода с потоковой передачейstream.get_final_message()
Полный разговорthread.messages
id ответа, от которого продолжается следующий ходthread.previous_message_id
Добавить сообщения без отправкиthread.append(...)
Изменить поля для последующих ходовthread.update(...)
Скопировать веткуthread.fork()
Поля и разговор для запуска новой веткиthread.params
Tool runner (исполнитель инструментов) в этой веткеthread.tool_runner()
Исполнитель инструментов без веткиtool_runner(..., thread=False)

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

  • Python: выйдите из блока with.
  • TypeScript: выйдите из цикла или вызовите abort().
  • Go: вызовите Close.
  • Java и Ruby: вызовите close().
  • C#: освободите перечислитель. Выход из await foreach делает это.
  • PHP: вызовите close().

В C# запрос отправляется, когда вы начинаете читать поток.

В C#, Go, Java и PHP после отказа thread.LastMessage по-прежнему возвращает ответ предыдущего хода или ничего на первом ходе. Считывайте отказ из событий потока.

Изменение полей. Обновление ничего не отправляет и применяется ко всем последующим ходам. Как только у ветки появляется ответ, вспомогательный класс отклоняет ход, изменяющий system или tools, а API отклоняет изменение любого другого фиксированного поля (см. Что отправлять в каждом запросе). Чтобы изменить одно из этих полей, начните новую ветку из params или создайте ответвление ветки и обновите его до первого хода.

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

Params. Params содержат поля вспомогательного объекта и весь разговор. Передайте их в метод, создающий вспомогательный объект, чтобы начать новую ветку, например с другим system (см. Что отправлять в каждом запросе) или с сокращённым messages, чтобы отбросить более поздние ходы. Ветка, начатая из params, отправляет каждое сообщение в том виде, в котором вы его передали, включая точки останова cache_control, поэтому не превышайте лимит в 4 (см. Кэширование подсказок в ветке). Кроме Ruby, params не включают параметры запроса, поэтому передайте их снова.

Структурированный вывод. Укажите формат вывода при создании вспомогательного объекта. Последующий ход не может его изменить. Способ получения разобранного результата зависит от SDK:

  • Python и TypeScript: вызовите thread.parse(...).
  • C#: создайте вспомогательный объект с помощью client.Beta.Messages.Thread<T>(...).
  • Go: Send выполняет демаршалинг в структуру, на которую указывает Params.OutputConfig.Format.Schema.
  • Java: создайте вспомогательный объект с помощью thread(...) и outputConfig(MyClass.class).
  • PHP: send() устанавливает parsed в текстовых блоках, когда outputConfig указывает класс модели.
  • Ruby: передайте output_config: {format: MyModel} в thread(...), затем прочитайте reply.parsed_output.

Ошибки

API возвращает ошибки из этой таблицы до запуска модели. Запрос не расходует токены, а ветка и время её истечения не меняются. error.type равен invalid_request_error для ошибок 400 и not_found_error для ошибки 404.

Статусerror_codeЗначениеЧто делать
404thread_not_foundAPI не может продолжить ветку.Отправьте полный разговор в новом запросе на создание.
400thread_fingerprint_mismatchФиксированное поле отличается от значения, сохранённого с веткой. Сообщение об ошибке называет поля.Сохраняйте фиксированные поля неизменными или начните новую ветку, чтобы изменить одно из них.
400thread_already_continuedКаждый id ответа можно продолжить один раз.Продолжайте от последнего id ответа в ветке. Если ваш клиент так и не получил этот ответ, выполните повторную отправку.
400thread_continue_in_flightДругой запрос на продолжение от этого id ответа всё ещё выполняется. Обычно это ваша собственная более ранняя попытка.Дождитесь её завершения и продолжайте от её id ответа или выполните повторную отправку.
400thread_unsupported_requestЗапрос использует функцию или настройку организации, которую ветки не поддерживают. error.details.unsupported называет её, если присутствует.Удалите эту функцию из запроса или отправьте полный разговор без thread.

Некоторые ошибки 400 для запросов ветки не содержат error_code, например запрос на продолжение без previous_message_id или запрос, включающий system или tools.

В следующем примере показано тело ошибки:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Функции, которые ветки не поддерживают

Ветки не поддерживают следующие функции:

API отклоняет большинство запросов, которые ветки не поддерживают, с ошибкой 400 и кодом thread_unsupported_request. Если error.details.unsupported присутствует, он содержит одно из следующих значений:

ЗначениеСмысл
context_managementЗапрос использует управление контекстом или сжатие, которые ветки не поддерживают.
cache_controlЗапрос содержит более 4 точек останова cache_control. См. Кэширование подсказок в ветке.
fallbacksЗапрос задаёт fallbacks, а ваша организация не может использовать fallbacks с ветками.
hipaaВ вашей организации включена готовность к HIPAA.
inference_hooksВ вашей организации включены хуки инференса.

API может добавлять значения в этот список. Если вы получили незнакомое значение, отправьте полный разговор без thread. Запрос, удовлетворяющий нескольким из этих условий, получает ошибку, которая называет только одно из них.

Ограничения

  • Нет API для получения списка, чтения или удаления ветки.
  • Ветки доступны в Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), и Claude in Microsoft Foundry.

Цены и ограничения скорости

Ветки не меняют цены и ограничения скорости.

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

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

Ветка содержит разговор, который API отправляет модели, system и tools из запроса на создание, а также отпечаток фиксированных полей, который используется для проверки последующих запросов. Файлы она содержит по ссылке, поэтому сохраняйте доступность всех файлов, используемых в разговоре, пока вы используете ветку.

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

См. также

Доступность

Ветки сообщений находятся в бета-версии для всех моделей.

Поддержка API

Обязательные бета-заголовки

Обзор бета-заголовков

Бета-заголовки позволяют получить доступ к экспериментальным функциям и новым возможностям моделей до того, как они станут частью стандартного API.

Обработка данных

Обзор обработки данных

Was this page helpful?