Переход на версию API 2026-10-21
Обновление интеграции с Claude API с версии API 2023-06-01 до 2026-10-21: какую версию SDK установить и какие изменения внести в код.
В этом руководстве перечислены изменения кода, необходимые для перехода с версии API 2023-06-01 на 2026-10-21. В разделе шаги обновления описано, что и в каком порядке нужно сделать.
Claude Code
Самый простой способ обновить ваш код
/claude-api api-versionШаги обновления
Переход на 2026-10-21
Если вы используете SDK, ваши запросы используют ту версию API, которая была актуальной на момент выпуска мажорной версии вашего SDK. Версии, указанные для вашего языка, — первые, которые используют
2026-10-21, поэтому обновитесь до них. Если вы вызываете API без SDK, установите заголовокanthropic-versionв значение2026-10-21.Обновите пакет
anthropicдо версии 2.0.0.Выпустите обновление вместе с исправлениями из следующего шага.
Обновите код с учётом критических изменений
Просмотрите критические изменения и обновите код для каждого из них, которое вас затрагивает. Также внесите изменения в код, которые требуются новой версии SDK или CLI.
Протестируйте с 2026-10-21
Протестируйте свою интеграцию с
2026-10-21перед выпуском.
Критические изменения
Messages API
Эти изменения применяются к запросам к Messages API (POST /v1/messages), к подсчёту токенов и к каждому запросу в пакете сообщений, созданном с 2026-10-21.
Блоки документов в сообщениях ассистента возвращают ошибку
Затрагивает вас, если вы отправляете блоки document непосредственно в сообщениях assistant.
В 2026-10-21 запрос, который помещает блок document непосредственно в сообщение assistant, возвращает ошибку 400. Вместо этого отправляйте документы в сообщениях user. Документ, вложенный в другой блок, например в результат инструмента веб-загрузки, который вернул Claude, по-прежнему принимается.
Цитаты в сообщениях пользователя возвращают ошибку
Затрагивает вас, если вы отправляете citations в блоках text в сообщениях user, в том числе внутри блоков search_result.
В 2026-10-21 запрос, который отправляет блок text с непустым массивом citations в сообщении user, возвращает ошибку 400. Удалите citations из этих блоков. Цитаты в блоках text в сообщениях assistant, например в предыдущих ответах Claude, которые вы отправляете обратно, по-прежнему принимаются, как и настройка "citations": {"enabled": true} для документов и результатов поиска.
Параметры сэмплирования удалены
Затрагивает вас, если вы отправляете temperature, top_p или top_k в запросах Messages или запросах пакетов сообщений.
В 2026-10-21 запрос, который отправляет temperature, top_p или top_k, возвращает ошибку 400, даже если значение параметра равно значению по умолчанию.
Удалите эти три параметра из своих запросов.
Начиная с последних мажорных версий, в SDK и CLI этих трёх параметров больше нет.
Без этих параметров запрос выполняет сэмплирование с их значениями по умолчанию, включая temperature, равную 1.0, — так же, как запрос 2023-06-01, в котором они не указаны. Модели, которые уже принимают только значения по умолчанию, такие как Claude 4.7 и более поздние модели, выполняют сэмплирование как прежде. На моделях, которые принимают другие значения, таких как Claude Sonnet 4.6, запрос, в котором temperature понижалась для более согласованного вывода, теряет этот эффект. Никакая другая настройка его не заменяет. Если запрос зависит от значения, отличного от значения по умолчанию, либо перестаньте отправлять этот параметр, либо оставьте этот запрос на 2023-06-01.
Admin API и Claude Enterprise Analytics API
Затрагивает вас, если ваш код читает поля ответов Admin API или Claude Enterprise Analytics API, перечисленные в следующих таблицах.
В 2026-10-21 ответы Admin API и Claude Enterprise Analytics API больше не содержат старых имён переименованных полей. Используйте вместо них новые имена.
Admin API:
| Эндпоинты | Старое имя | Новое имя |
|---|---|---|
| Группы RBACДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.: создание, получение списка, получение и обновление | roles | role_ids |
| Участники групп RBACДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.: получение списка и добавление, а также ответ на удаление участникаДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. | group_id | rbac_group_id |
| Роли RBACДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.: получение списка и получение | name | display_name |
| Ограничения скорости организацииДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. и рабочего пространстваДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.: получение списка, а также ответ на установку ограничений скорости рабочего пространстваДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. | group_type | group.type |
| Ключи APIДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.: получение списка, получение и обновление | workspace_id | scope (другие значения; см. workspace_id в ключах API) |
Claude Enterprise Analytics API:
| Эндпоинты | Старое имя | Новое имя |
|---|---|---|
| Отчёты по использованиюДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. и стоимостиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. для каждого пользователя | actor.email | actor.email_address |
| Сводки активностиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. | summaries | data |
Параметр запроса group_type в эндпоинтах получения списка ограничений скорости и фильтр workspace_id в эндпоинте получения списка ключей API не изменились.
workspace_id в ключах API
Затрагивает вас, если ваш код читает workspace_id в ключах API.
В 2023-06-01 поле workspace_id ключа API содержит ID рабочего пространства, к которому привязан ключ, или null для ключа, привязанного к рабочему пространству по умолчанию, и для ключа, который не привязан к одному рабочему пространству (ключ для всех рабочих пространств).
В 2026-10-21 поле workspace_id удалено. Вместо него читайте scope: для ключа, привязанного к рабочему пространству, включая рабочее пространство по умолчанию, scope.workspace_id содержит реальный ID этого рабочего пространства, а ключ для всех рабочих пространств имеет scope, равный {"type": "organization"}, без workspace_id.
Если ваш код рассматривал null в workspace_id как рабочее пространство по умолчанию, вместо этого сравнивайте scope.workspace_id с ID вашего рабочего пространства по умолчанию. Чтобы найти этот ID, вызовите эндпоинт Список рабочих пространствДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. с include_default=true и возьмите рабочее пространство с именем "Default".
Изменения SDK и CLI
Более ранние версии SDK и CLI отправляли anthropic-version: 2023-06-01 с каждым запросом. Версии, указанные в разделе Переход на 2026-10-21, отправляют 2026-10-21, включая их клиенты для Amazon Bedrock и Google Cloud. Изменения из раздела Критические изменения применяются и к ним: удалённые параметры и старые имена полей также исчезли из типов SDK, а также из флагов и вывода CLI.
MessageParam — объединение с отдельным типом для каждой роли
В более ранних версиях MessageParam был одним типом для всех ролей. Теперь у каждой роли есть собственный тип: UserMessageParam, AssistantMessageParam и SystemMessageParam. BetaMessageParam разделён так же — на BetaUserMessageParam, BetaAssistantMessageParam и BetaSystemMessageParam. Запросы, которые отправляет SDK, содержат те же поля и значения, что и раньше.
Сообщение, записанное как литерал словаря, например {"role": "user", "content": "Hello"}, не требует изменений.
В v1 anthropic.types.MessageParam был одним TypedDict. В v2 это объединение трёх типов, а anthropic.types.beta.BetaMessageParam — объединение своих трёх типов. Оба имени по-прежнему работают в аннотациях, например list[MessageParam].
Вызов любого из этих имён теперь вызывает TypeError, и проверка типов помечает его. Записывайте сообщение как словарь:
# До
message = MessageParam(role="user", content="Hello")
# После
message: MessageParam = {"role": "user", "content": "Hello"}Наследование от любого из этих имён также вызывает TypeError. Наследуйтесь от типа для конкретной роли, например UserMessageParam.
Остальные изменения влияют только на проверку типов. Словарь, чей role — переменная, которая может содержать более одной роли, не соответствует ни одному типу в объединении, поэтому формируйте словарь отдельно для каждой роли:
# До
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
return {"role": role, "content": text}
# После
def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam:
if role == "user":
return {"role": "user", "content": text}
return {"role": "assistant", "content": text}Ещё два изменения касаются только BetaMessageParam:
clear_atиoutput_config— ключиBetaSystemMessageParam, поэтому у сообщения пользователя или ассистента их быть не может.contentнеобязателен вBetaSystemMessageParam, поэтому pyright сообщает оmessage["content"]. Читайте его черезmessage.get("content")или сначала проверьте, чтоmessage["role"]не равен"system".
Перечисления с одним значением стали константами
Это затрагивает SDK для C#, Go, Java, PHP и Ruby, а также один флаг CLI. В более ранних версиях обязательное поле, которое может содержать только одно значение, имело собственный тип перечисления с единственным членом. Теперь эти поля являются константами, а типы перечислений удалены. JSON, который SDK отправляет и читает, остаётся прежним.
--type необязателен в ant beta:sessions:resources add. file — единственное значение, которое --type может там принимать, поэтому v2 отправляет его за вас. Команды, которые по-прежнему передают --type file, продолжают работать, поэтому ничего менять не нужно.
Клиентское сжатие удалено из исполнителя инструментов
Это затрагивает SDK для TypeScript и Ruby. Клиентское «compaction» (сжатие контекста) в «tool runner» (исполнителе инструментов) удалено в пользу серверного сжатия, которое суммирует разговор внутри API, а не с помощью дополнительного запроса от клиента.
Опция compactionControl и модуль @anthropic-ai/sdk/lib/tools/CompactionControl удалены. Опция перестала работать в v0.129.0, где её передача выбрасывала AnthropicError. Её нет в типе параметров исполнителя инструментов, поэтому TypeScript сообщает о ней как о неизвестном свойстве.
Чтобы сохранить автоматическое сжатие при достижении порога токенов:
// До
const runner = client.beta.messages.toolRunner({
// ...
compactionControl: { enabled: true, contextTokenThreshold: 100_000 }
});
// После
const runner = client.beta.messages.toolRunner({
// ...
betas: ["compact-2026-01-12"],
context_management: {
edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }]
}
});Чтобы самостоятельно решать, когда сжимать разговор, вызывайте runner.compactBeforeNextTurn().
Порог срабатывания должен составлять не менее 50 000 токенов. Другие параметры (pause_after_compaction, пользовательские instructions) описаны в разделе сжатие.
Text Completions удалён
Устаревший Text Completions API удалён из SDK для TypeScript, Go, Java и Ruby, а также из CLI. Новые модели и функции его не поддерживают. Используйте вместо него Messages API.
betas удалён из небета-методов Models
Небета-методы Models больше не принимают betas, а команды ant models больше не принимают --beta. Чтобы отправлять бета-заголовки, вызывайте те же методы у client.beta.models или используйте ant beta:models в CLI. В SDK эти методы возвращают BetaModelInfo, тогда как небета-методы возвращают ModelInfo.
client.models.retrieve() и client.models.list() больше не принимают betas (его передача вызывает TypeError, и проверка типов помечает это), а у anthropic.types.ModelListParams больше нет ключа betas.
# До
page = client.models.list(betas=[beta])
# После
page = client.beta.models.list(betas=[beta])Ключи API отправляются как Authorization: Bearer
SDK и CLI отправляют ваш ключ API как Authorization: Bearer <key>, а не в заголовке X-Api-Key, поэтому измените любой прокси или шлюз, который читает или устанавливает X-Api-Key, чтобы он использовал Authorization, или отправляйте ключ в X-Api-Key самостоятельно. Также измените код в вашей собственной программе, который читает X-Api-Key, например промежуточное ПО, фильтр логов или тестовую заглушку. Claude API принимает ключ в любом из этих заголовков.
# Before
X-Api-Key: <key>
# After
Authorization: Bearer <key>Authorization — это заголовок, который уже использует auth_token.
Это относится к аргументу api_key и переменной окружения ANTHROPIC_API_KEY у Anthropic и AsyncAnthropic, а также к api_key и ANTHROPIC_AWS_API_KEY у AnthropicAWS. AnthropicFoundry по-прежнему отправляет свой ключ как x-api-key, а AnthropicBedrockMantle уже отправлял «bearer token» (токен на предъявителя).
Если прокси или шлюз читает X-Api-Key
Верните ключ на прежнее место с помощью функции auth в HTTP-клиенте. Она выполняется для каждого запроса, который отправляет клиент, включая повторные попытки:
import httpx2
from anthropic import Anthropic, DefaultHttpxClient
def send_x_api_key(request: httpx2.Request) -> httpx2.Request:
if request.headers.get("Authorization") == f"Bearer {api_key}":
del request.headers["Authorization"]
request.headers["X-Api-Key"] = api_key
return request
client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key))AsyncAnthropic принимает ту же функцию в http_client=DefaultAsyncHttpxClient(auth=send_x_api_key).
Если вы устанавливали или удаляли X-Api-Key в запросе
Это касается SDK для Python, TypeScript, Go, PHP и Ruby.
Если вы удаляли X-Api-Key, чтобы запрос отправлял только токен аутентификации, удалите этот код вместо того, чтобы изменять его, потому что удаление Authorization удалит токен. Клиент хранит одни учётные данные, поэтому убедитесь, что это именно токен: если в коде ничего не передано и заданы обе переменные ANTHROPIC_API_KEY и ANTHROPIC_AUTH_TOKEN, клиент использует ключ.
Код, который передаёт extra_headers={"X-Api-Key": omit}, чтобы не отправлять ключ в запросе, больше этого не делает. Вместо этого передавайте extra_headers={"Authorization": omit}.
extra_headers={"X-Api-Key": other_key} больше не заменяет ключ клиента: отправляются оба ключа. Чтобы отправить другой ключ с одним запросом, передайте extra_headers={"Authorization": f"Bearer {other_key}"}.
Клиент хранит одни учётные данные
Ключ API и токен аутентификации теперь используют один заголовок, поэтому клиент SDK хранит одни учётные данные. Если в коде ничего не передано, он следует порядку приоритета учётных данных.
v1 отправляла и ключ API, и токен аутентификации, если у клиента были оба, каждый в своём заголовке. Учётные данные — это одно из api_key, auth_token, credentials, config или profile.
- Передавайте не более одного. Два или более в конструкторе либо в одном вызове
copy()илиwith_options()вызываютValueError.Noneне учитывается. v1 вызывалаTypeError, и только для двух изcredentials,configиprofile. - Переданные вами учётные данные — единственные. Как и в v1, клиент не ищет другие в окружении или на диске.
- Если ничего не передано, используется только первое заданное из следующего:
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN, профиль, указанный вANTHROPIC_PROFILE, переменные «workload identity federation» (федерации удостоверений рабочих нагрузок), активный профиль на диске (тот, который указан в файлеactive_config, иначеdefault). Если заданы обе первые переменные, клиент один раз записывает предупреждение в журнал. v1 использовала активный профиль раньше переменных федерации, если была заданаANTHROPIC_CONFIG_DIRили существовал файлactive_config; задайтеANTHROPIC_PROFILE, чтобы продолжить его использовать. copy()иwith_options()заменяют. Переданные вами учётные данные заменяют собственные учётные данные клиента, какого бы вида ни были те и другие. Базовый URL и заголовки, пришедшие из конфигурации или профиля старых учётных данных, уходят вместе с ними, и используются те, что принадлежат новым учётным данным. Переданный вами базовый URL сохраняется.
client = Anthropic(api_key=key, auth_token=token)
# До: отправлялись `X-Api-Key: <key>` и `Authorization: Bearer <token>`
# После: вызывает `ValueError`Клиенты платформ сохраняют собственные правила. AnthropicAWS принимает auth_token рядом с api_key без ошибки и отправляет ключ.
Подробности приведены в docstring-комментариях Anthropic.__init__ и Anthropic.copy в _client.py.
Если вы полагались на отправку обоих, например токена для шлюза и ключа для API за ним, передайте токен как auth_token и задайте X-Api-Key в default_headers. Настройте шлюз так, чтобы он удалял свой заголовок Authorization перед пересылкой запроса. Claude API ожидает одни учётные данные для каждого запроса.
Изменения в одном SDK или в CLI
Каждое из этих изменений затрагивает один SDK или CLI.
--api-key и --auth-token удалены. ant больше не принимает ключ API или токен аутентификации в качестве значения флага, потому что значение в командной строке видно в истории оболочки и в списках процессов. Оба флага выводили предупреждение об устаревании начиная с v1.27.0. Команда, которая всё ещё передаёт один из них, завершается с flag provided but not defined.
| Удалено | Используйте вместо этого |
|---|---|
--api-key <key> | ANTHROPIC_API_KEY, --api-key-stdin или ant auth login |
--auth-token <token> | ANTHROPIC_AUTH_TOKEN или --auth-token-stdin |
# До
ant --api-key "$KEY" models list
# После: из переменных окружения
export ANTHROPIC_API_KEY="$KEY"
ant models list
# После: из менеджера секретов
op read op://vault/anthropic/api-key | ant --api-key-stdin models list--api-key-stdin и --auth-token-stdin читают весь стандартный ввод, поэтому команда, использующая один из них, берёт тело запроса из флагов.
ant auth status, приглашение при первом запуске ant apply и примечание о нескольких источниках аутентификации теперь называют эти учётные данные ANTHROPIC_API_KEY и ANTHROPIC_AUTH_TOKEN, тогда как раньше выводили --api-key / ANTHROPIC_API_KEY и --auth-token / ANTHROPIC_AUTH_TOKEN.
Лицензия — Apache 2.0
Начиная с версий, указанных в разделе Переход на 2026-10-21, SDK и CLI распространяются под лицензией Apache License, Version 2.0. Более ранние версии остаются под лицензией MIT. Изменения в коде не требуются. Если вы отслеживаете лицензии своих зависимостей, обновите соответствующие записи.
- TypeScript: Пакеты платформ (
@anthropic-ai/bedrock-sdk,@anthropic-ai/vertex-sdk,@anthropic-ai/foundry-sdk,@anthropic-ai/aws-sdkи@anthropic-ai/google-cloud-sdk) меняют лицензию в своих собственных выпусках 1.0.0. - C#: Остальные пакеты (
Anthropic.Bedrock,Anthropic.Vertex,Anthropic.Foundry,Anthropic.Aws,Anthropic.GoogleCloudиAnthropic.Mcp) меняют лицензию в своих собственных выпусках 1.0.0. - Java: Изменение распространяется на все артефакты
com.anthropic.
Эта страница была полезной?