Anthropic이 Claude API의 새 버전 번호 2026-10-21을 공개했다. 개발자들은 2023년부터 지금까지 요청 헤더에 anthropic-version: 2023-06-01을 써 왔는데, 이번이 그 이후 처음으로 나온 정식 새 버전이다.
가장 눈에 띄는 변경은 Messages API에서 temperature, top_p, top_k 세 가지 샘플링 매개변수가 제거됐다는 점이다. 마이그레이션 문서에 따르면 새 버전으로 요청을 보낼 때 이 세 필드가 하나라도 들어 있으면 기본값을 그대로 넣었더라도 곧바로 400 오류가 반환된다. 보내지 않으면 기본값으로 샘플링되며 temperature는 1.0이다. 이전 버전에서 매개변수를 생략했을 때와 같은 효과다.
이전 버전은 지원 중단(deprecated)되지 않았다. 문서의 권고는 간단명료하다. 기본값이 아닌 샘플링 값에 의존하는 요청은 매개변수를 없애거나, 계속 2023-06-01에 머물라는 것이다.
누가 영향을 받나
Claude 4.7 이후 모델에서는 이번 매개변수 삭제로 실질적인 변화가 거의 없다. 문서는 이들 모델이 원래부터 기본값만 받아들였다고 설명한다. 영향을 받는 쪽은 Claude Sonnet 4.6 같은 이전 모델을 계속 쓰면서 출력 안정성을 위해 일부러 온도를 낮춰 둔 애플리케이션이다. 문서는 이런 요청이 업그레이드 후 원래의 효과를 잃으며 이를 대체할 다른 설정은 없다고 분명히 적었다.
샘플링 매개변수 외에도 Messages API에는 400 오류가 나는 변경이 두 가지 더 있다.
- assistant 메시지에
document블록을 직접 넣으면 오류가 난다. 문서는 user 메시지에 넣어야 한다. - user 메시지의 text 블록에 비어 있지 않은
citations를 담아도 마찬가지로 오류가 난다.
관리 쪽에서도 이름이 바뀌었다. Admin API에서 RBAC 그룹의 roles는 role_ids로 바뀌고, API 키의 workspace_id는 제거되어 scope를 읽는 방식이 됐다. 엔터프라이즈 분석 엔드포인트에서는 actor.email이 actor.email_address로 바뀐다. 새 버전에서는 이전 필드 이름이 더 이상 반환되지 않는다.
SDK도 함께 메이저 버전 상승
각 언어의 공식 SDK가 이번에 모두 메이저 버전을 올렸고, 새 버전은 기본적으로 2026-10-21을 보낸다. Python 패키지 anthropic은 2.0.0, TypeScript의 @anthropic-ai/sdk는 1.0.0, Go는 v2(임포트 경로에 /v2를 붙여야 함), Java는 3.0.0, C#은 13.0.0, PHP는 1.0.0, Ruby는 2.0.0이다. 명령줄 도구 ant는 2.0.0으로 올랐다.
Go 사용자는 한 가지 더 주의해야 한다. CLI의 모듈 경로가 github.com/anthropics/anthropic-cli/v2로 바뀌었는데, 문서는 이전 경로로 go install을 하면 계속 최신 v1이 설치되며 오류도 경고도 나타나지 않는다고 특별히 당부한다.
Amazon Bedrock에서는 새 버전이 Claude 4.7 이후 모델에만 열린다. Bedrock에서 Opus 4.6 같은 이전 모델을 계속 호출하는 경우, 현재 SDK 버전에 머물거나 모델을 먼저 바꾼 뒤 업그레이드해야 한다.
API 키가 다른 헤더로 옮겨 간다
중국 개발자에게 영향 범위가 가장 클 만한 변경은 SDK 변경 사항 속에 숨어 있다. 새 SDK와 CLI는 API 키를 더 이상 X-Api-Key 헤더에 넣지 않고 Authorization: Bearer <key>로 통일했다.
Claude API 자체는 두 헤더를 모두 받아들이므로 공식 엔드포인트에 직접 연결하는 프로그램은 영향이 없다. 문제는 중간 계층이다. 자체 구축한 리버스 프록시, API 게이트웨이, 사용량 집계 미들웨어 가운데 X-Api-Key에서 키를 읽어 인증이나 과금을 하는 것들은 SDK를 올리는 순간 키를 읽지 못하게 된다. 문서는 두 가지 해법을 제시한다. 게이트웨이가 Authorization을 읽도록 고치거나, 클라이언트에서 수동으로 키를 X-Api-Key에 다시 넣는 것이다.
또 하나의 연쇄 변경은 클라이언트 하나가 한 종류의 자격 증명만 가질 수 있다는 점이다. 과거에는 Python에서 api_key와 auth_token을 함께 넘기면 두 헤더가 모두 전송됐지만, 이제는 바로 ValueError가 발생한다.
2년 넘은 옛 버전 번호를 돌아보며
2023-06-01이라는 버전 번호는 Claude 2 시대부터 Claude 5 시리즈까지 Claude의 모든 진화를 덮어 왔다. 그 사이 추가된 도구 호출, 프롬프트 캐싱, 확장 사고 같은 기능은 대부분 beta 헤더와 새 필드로 덧붙여졌고, 버전 번호 자체는 움직이지 않았다.
샘플링 매개변수의 퇴장은 사실 예고가 있었다. Claude 4.7부터 모델은 기본값만 받아들였고, 새 모델에서 온도를 조절해도 일찍부터 효과가 없었다. 이번에는 그 규칙을 API 계약에 명문화해 요청이 입구에서 바로 실패하게 함으로써, 호출하는 쪽이 매개변수가 아직 작동한다고 착각하지 않도록 했다.
이전 버전을 얼마나 유지할지에 대해 마이그레이션 문서는 일정을 제시하지 않았고, Anthropic도 현재까지 2023-06-01의 종료일을 공개하지 않았다.
참고 출처: Claude 플랫폼 마이그레이션 문서, Claude 개발자 공식 계정, CocoLoop. 각 언어 SDK 버전 번호, 오류 조건, Bedrock 적용 모델 범위는 공식 마이그레이션 문서를 기준으로 한다.