Claude API w wersji 2026-10-21: co psuje aktualizacja SDK i jak ją zablokować

21 października 2026 Anthropic wydał wersję API 2026-10-21 i równocześnie nowe główne wydania wszystkich oficjalnych SDK oraz narzędzia ant. Najważniejsze dla Twojego kodu: te wydania domyślnie wysyłają nową wersję API, więc podniesienie SDK o jeden numer główny jest jednocześnie migracją API. Nie ma osobnego przełącznika, który można zostawić na później.

Migracja nie jest przymusowa. Dokumentacja zaleca najnowszą wersję, ale starsze SDK nadal wysyłają 2023-06-01, a w przeczytanych przeze mnie stronach nie ma daty jej wyłączenia. Ryzyko jest więc inne niż przy wycofaniu modelu: nie chodzi o termin, tylko o to, że automatyczna aktualizacja zależności (bot, pip install -U, luźne ograniczenie wersji) może wciągnąć nowy numer główny bez Twojej decyzji.

Ten wpis opiera się na przewodniku migracji i notatkach wydania z platform.claude.com. Gdzie to moja interpretacja, a nie zapis z dokumentacji, zaznaczam.

W skrócie:

• Nowe wersje: Python SDK 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 i ant 2.0.0.
• Wersja API 2026-10-21 zwraca błąd 400 przy temperature, top_p i top_k (nawet z wartością domyślną), przy dokumentach w wiadomościach assistant i przy cytowaniach w blokach tekstowych wiadomości user.
• Nowe SDK wysyłają klucz API w nagłówku Authorization: Bearer, a nie w X-Api-Key. To może złamać bramki i proxy, które czytają stary nagłówek.
• Zostać na starym zachowaniu możesz, przypinając wersję SDK poniżej nowego numeru głównego albo wysyłając anthropic-version: 2023-06-01 w żądaniach bez SDK.

Które wersje SDK wysyłają nową wersję API

Każdy numer główny SDK wysyła jedną wersję API i nowy numer główny pojawia się razem z nową wersją API. Dla 2026-10-21 są to:

W dniu publikacji tego wpisu dokumentacja podaje już kolejne wydania: 2.1.0 dla Pythona, 1.1.0 dla TypeScriptu i 13.1.0 dla C#. Starsze wydania wysyłały anthropic-version: 2023-06-01 z każdym żądaniem.

Nowe wydania mają też licencję Apache 2.0 zamiast MIT (wcześniejsze wersje zostają na MIT). Jeśli pilnujesz licencji zależności, zaktualizuj wpisy.

Co zmienia się w API, a co w samych SDK

Zmiany dzielą się na dwie grupy i warto je rozdzielić, bo działają niezależnie. Pierwsza grupa wynika z wersji API: dotyczy każdego, kto wyśle nagłówek 2026-10-21, także z cURL-a. Druga wynika z nowych SDK i ant: dotyczy tylko tych narzędzi, nie samego API.

Najbardziej boli pierwszy wiersz, bo dla temperature nie ma bezpośredniego zamiennika. Szczegóły poniżej.

Parametry temperature, top_p i top_k: co się stanie

W wersji 2026-10-21 żądanie, które zawiera temperature, top_p albo top_k, zwraca 400, nawet gdy wartość jest domyślna. Dotyczy to Messages API, zliczania tokenów i każdego żądania w Message Batches utworzonych z tą wersją. W samych SDK te trzy parametry zniknęły z typów i z flag CLI.

Co to znaczy w praktyce, według przewodnika:

• Bez tych parametrów model próbkuje z wartościami domyślnymi, w tym z temperature równą 1,0. To samo robi żądanie 2023-06-01, które ich nie podaje.
• Modele, które już akceptowały tylko wartości domyślne (Claude 4.7 i nowsze), zachowują się jak dotąd. O tej wcześniejszej zmianie na poziomie modeli piszę w tekście Claude Opus 4.7: model, który zmienił API, a o jej powtórce w tańszym tierze w opisie Claude Haiku 5.5.
• Na modelach, które przyjmują inne wartości (przewodnik podaje przykład Claude Sonnet 4.6), żądanie z obniżoną temperature traci ten efekt. Przewodnik pisze: żadne inne ustawienie jej nie zastępuje.
• Jeśli żądanie zależy od niestandardowej wartości, albo przestajesz ją wysyłać, albo to żądanie zostaje na 2023-06-01.

Moja ocena: jeśli przeszedłeś już na modele 4.7 lub nowsze, ten punkt dotknie Cię najmniej. Jeśli masz klasyfikator lub ekstraktor na starszym modelu z temperature ustawioną na 0, przetestuj go bez tego parametru, zanim podniesiesz SDK.

Dokumenty w wiadomościach assistant i cytowania w wiadomościach user

Dwie pozostałe zmiany w Messages API są wąskie, ale zwracają 400, więc łatwo je pominąć w testach.

Dokumenty w odpowiedziach asystenta. Blok document umieszczony bezpośrednio w wiadomości assistant zwraca 400. Dokument należy wysłać w wiadomości user. Dokument zagnieżdżony w innym bloku, na przykład w wyniku narzędzia pobierania stron, który zwrócił Claude, nadal przechodzi.

Cytowania w wiadomościach użytkownika. Blok text z niepustą tablicą citations w wiadomości user zwraca 400, także wewnątrz bloku search_result. Cytowania w blokach text wiadomości assistant (na przykład wcześniejsze odpowiedzi Claude’a odsyłane w historii) są nadal akceptowane. Działa też ustawienie "citations": {"enabled": true} na dokumentach i wynikach wyszukiwania.

Typowy ślad w kodzie: logika, która przebudowuje historię rozmowy, składa ją z zapisanych fragmentów albo wstrzykuje do niej dokumenty i źródła we własnym formacie.

Klucz API w nagłówku Authorization: co sprawdzić w bramkach

To zmiana, która najłatwiej wywróci produkcję, bo nie wymaga żadnej zmiany w Twoim kodzie. Nowe SDK i ant wysyłają klucz jako Authorization: Bearer <klucz>, a nie w nagłówku X-Api-Key. Samo API przyjmuje klucz w obu nagłówkach, więc program, który łączy się z API bezpośrednio, nie wymaga zmian. Kłopot mają pośrednicy, którzy czytają albo ustawiają X-Api-Key.

Sprawdź u siebie:

1. Bramki i proxy. Reguły, które uwierzytelniają, limitują albo przepisują ruch po X-Api-Key, przestaną widzieć klucz. Zmień je tak, by czytały Authorization, albo ustaw X-Api-Key po stronie klienta.
2. Logowanie i maskowanie sekretów. To moja uwaga, nie zapis z przewodnika: jeśli narzędzia maskują klucz tylko w X-Api-Key, sprawdź, czy maskują też Authorization.
3. Middleware i własne fetch. Kod, który czyta klucz z x-api-key, musi czytać authorization, gdzie klucz stoi po słowie Bearer .
4. Ręczne nagłówki. W SDK Python, TypeScript, Go, PHP i Ruby kod ustawiający X-Api-Key na żądaniu przestaje zastępować klucz klienta: wychodzą wtedy dwa klucze. Kod usuwający X-Api-Key, żeby wysłać samo uwierzytelnienie tokenem, przestaje działać, bo usunąć trzeba teraz Authorization.
5. Klient trzyma tylko jedno poświadczenie. Wcześniej klient z kluczem i tokenem wysyłał oba, każdy w osobnym nagłówku. Teraz przekazanie dwóch (na przykład api_key i auth_token w Pythonie) kończy się błędem (ValueError, w TypeScripcie TypeError). Jeśli wysyłasz token do bramki i klucz do API za nią, token przekaż jako auth_token, a X-Api-Key dopisz własnym nagłówkiem, i niech bramka usunie swój Authorization przed przekazaniem dalej.

Jeśli bramka musi dalej dostawać X-Api-Key, przewodnik pokazuje przeniesienie klucza z powrotem. W TypeScripcie wystarczy:

const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null }
});

W Pythonie robi się to funkcją auth na kliencie HTTP, która zamienia Authorization na X-Api-Key w każdym żądaniu, także w ponowieniach. Samo ant nie ma flagi ani zmiennej środowiskowej do dodawania własnych nagłówków, więc nie wyśle X-Api-Key: bramkę trzeba zmienić po jej stronie.

Wyjątki warte uwagi: klient Foundry nadal wysyła klucz jako x-api-key, a klienci Bedrock Mantle już wcześniej używali tokenu typu bearer.

Pozostałe usunięcia: Text Completions, kompakcja i flagi ant

Text Completions. Stare API Text Completions zostało usunięte z SDK TypeScript, Go, Java i Ruby oraz z CLI (komenda ant completions create zniknęła). Przewodnik odsyła do Messages API. W jego opisie nie ma wzmianki o Pythonie, C# i PHP, więc nie twierdzę, że tam coś zniknęło.

Kliencka kompakcja w tool runnerze. W SDK TypeScript (compactionControl) i Ruby (compaction_control:) usunięto kompakcję po stronie klienta na rzecz kompakcji po stronie API. Według przewodnika opcja przestała działać już wcześniej: w TypeScripcie od v0.129.0, w Ruby od v1.74.0 jej podanie rzucało błąd. Zamiennik to nagłówek beta compact-2026-01-12 i edycja compact_20260112 w context_management, z progiem co najmniej 50 000 tokenów. To inna rzecz niż kompakcja bezczynnych sesji w Claude Code, która jest funkcją narzędzia, a nie parametrem API.

Flagi w ant. --api-key i --auth-token zostały usunięte, bo wartość na linii poleceń widać w historii powłoki i w liście procesów. Polecenie, które ich używa, kończy się błędem flag provided but not defined. Zamiast tego użyj ANTHROPIC_API_KEY, --api-key-stdin albo ant auth login (dla tokenu: ANTHROPIC_AUTH_TOKEN lub --auth-token-stdin). Instalujący ant przez go install muszą dopisać /v2 do ścieżki modułu, a stara ścieżka dalej instaluje najnowszą wersję 1 bez błędu i ostrzeżenia.

Admin API i Enterprise Analytics API: zmienione pola

W 2026-10-21 odpowiedzi tych interfejsów nie zawierają starych nazw pól. Jeśli czytasz je w skryptach raportowych, zmień nazwy:

Najbardziej zdradliwa jest zmiana w kluczach API. Dawniej workspace_id równe null oznaczało klucz domyślnego workspace’u albo klucz dla wszystkich workspace’ów. Teraz klucz związany z workspace’em (także domyślnym) ma scope.workspace_id z prawdziwym identyfikatorem, a klucz dla wszystkich workspace’ów ma scope równy {"type": "organization"} bez workspace_id. Kod, który traktował null jako workspace domyślny, musi porównywać scope.workspace_id z identyfikatorem tego workspace’u. Znajdziesz go przez List Workspaces z include_default=true.

Zmiany w typach SDK

Nowe wydania zmieniają też typy, co przy kompilacji lub sprawdzaniu typów pokaże błędy, choć wysyłane żądania są te same. MessageParam przestał być jednym typem dla wszystkich ról i jest teraz unią trzech: UserMessageParam, AssistantMessageParam i SystemMessageParam (podobnie BetaMessageParam). W Pythonie wywołanie MessageParam(...) rzuca TypeError, więc wiadomość zapisuje się jako słownik. Wiadomość zapisaną jako literał słownika, na przykład {"role": "user", "content": "Hello"}, nie trzeba zmieniać. Do tego Go 2 wymaga Go 1.25 lub nowszego. W SDK dla C#, Go, Java, PHP i Ruby pola o jednej możliwej wartości stały się stałymi, a typy enum o jednej wartości zniknęły. W TypeScripcie pakiety platformowe (Bedrock, Vertex, Foundry, AWS, Google Cloud) trzeba podnieść do v1 razem z głównym SDK, bo inaczej menedżer pakietów zainstaluje obok drugą, starszą kopię.

Jak zablokować automatyczną aktualizację do nowego SDK

Cel: żadna zależność nie przeskoczy numeru głównego bez Twojej wiedzy. Poniższe jest moją rekomendacją, oparte na zapisach z przewodnika.

1. Ogranicz zakres wersji w manifeście. Dla Pythona sensowne jest anthropic<2, dla npm zakres, który nie dopuszcza 1.0.0 i wyżej, dla Rubiego zakres poniżej 2. Unikaj latest, * i >= bez górnej granicy.
2. Użyj pliku blokującego i zatwierdzaj aktualizacje ręcznie. Przypięte wersje w uv.lock, package-lock.json lub pnpm-lock.yaml oraz przegląd pull requestów od botów robią to, czego sam zakres nie zrobi.
3. PHP: uważaj na composer require. Przewodnik zaznacza, że composer require "anthropic-ai/sdk" podnosi pakiet do 1.0.0, a sam composer update zostaje w obecnym ograniczeniu wersji.
4. Go: nowy numer główny to nowa ścieżka importu. Wersja 2 używa .../anthropic-sdk-go/v2, więc go get na starej ścieżce nie przeskoczy sam.
5. Przypnij anthropic-version tam, gdzie wysyłasz żądania sam. Bez SDK ustaw nagłówek anthropic-version: 2023-06-01, a przy migracji 2026-10-21. Nagłówek jest wymagany.
6. Nie nadpisuj wersji w nowym SDK, żeby wrócić do temperature. Dokumentacja Pythona pokazuje, że nagłówek anthropic-version można nadpisać w default_headers, ale ostrzega, że może to dać błędne typy i niezdefiniowane zachowanie. Ponadto nowe SDK nie ma już tych parametrów w typach. Nie testowałem takiego obejścia i go nie polecam: stabilniej zostawić usługę na starym SDK.
7. Amazon Bedrock ze starszymi modelami. 2026-10-21 jest tam dostępna tylko dla Claude 4.7 i nowszych. Dla starszych modeli zostań na dzisiejszej wersji SDK albo na wysyłanej dziś wersji API, a aby je przenieść, najpierw przełącz je na model 4.7 lub nowszy.

Lista kontrolna przed podniesieniem SDK

• Wyszukaj w repozytorium temperature, top_p, top_k i usuń je albo zostaw tę usługę na starej wersji.
• Przejrzyj kod budujący historię rozmowy pod kątem dokumentów w wiadomościach assistant i citations w wiadomościach user.
• Sprawdź bramki, proxy, reguły WAF, limity i maskowanie logów pod kątem X-Api-Key i Authorization.
• Poszukaj miejsc, gdzie klient dostaje jednocześnie klucz i token.
• Poszukaj completions, compactionControl i compaction_control w TypeScripcie, Go, Javie i Ruby.
• Sprawdź skrypty z ant: --api-key, --auth-token, ścieżkę go install.
• Zaktualizuj odczyt pól Admin API i Enterprise Analytics API.
• Uruchom testy na wersji 2026-10-21 przed wdrożeniem. Przewodnik zaleca wydanie aktualizacji razem z poprawkami kodu.

Podobną pracę z przeglądem kodu przed migracją opisałem przy wyłączeniu GPT-4o i GPT-4.1 w API OpenAI. Różnica jest istotna: tam jest data wyłączenia (14 stycznia 2027), tu dokumentacja żadnej nie podaje.

Najczęstsze pytania o wersję API 2026-10-21

Czy muszę migrować na 2026-10-21? Dokumentacja tego nie wymaga i na przeczytanych przeze mnie stronach nie podaje daty wyłączenia 2023-06-01, choć zaleca najnowszą wersję. Czy termin pojawi się później, nie wiadomo, więc śledź notatki wydania.

Czy aktualizacja SDK sama przełączy wersję API? Tak. Nowy numer główny wysyła 2026-10-21 domyślnie. Aktualizacja w obrębie tego samego numeru głównego wersji API nie zmienia.

Czy mogę dalej używać temperature? Tylko na 2023-06-01, czyli ze starym SDK albo z własnym nagłówkiem przy wywołaniach bez SDK. Na 2026-10-21 żądanie z tym parametrem zwraca 400 na każdym modelu.

Czy wywołania cURL też się zmienią? Tylko jeśli sam ustawisz anthropic-version: 2026-10-21. Klucz w x-api-key nadal działa, bo API akceptuje oba nagłówki.

Czy ceny lub modele się zmieniły? Notatki i przewodnik, które przeczytałem, o tym nie mówią. Nie opisuję tu cen.

Czy zmiana Bearer dotyczy chmur? Zależy od klienta. Klienci Foundry nadal wysyłają x-api-key, a klienci Bedrock Mantle już wcześniej używali tokenu bearer.

Przy migracji pomaga polecenie /claude-api api-version z Claude Code 2.1.307 (21 października), które przenosi kod na wersję API 2026-10-21. Co zmieniły kolejne wydania Claude Code, opisuję w tekście o wersjach 2.1.309–2.1.312.

Źródła

• Migrating to API version 2026-10-21 (przewodnik migracji) - Anthropic, 21 października 2026
• Claude Platform release notes - wpis z 21 października 2026
• API versions - historia wersji API
• SDKs, CLI, and libraries - tabela najnowszych wersji
• Python SDK, sekcje Default headers i Semantic versioning
• Wydanie v2.0.0 repozytorium anthropic-sdk-python