Claude API를 호출하는 코드에 temperature를 넣어뒀다면, 조만간 그 요청이 400 에러로 막힌다. Anthropic이 2026년 10월 21일 공식 발표한 API 버전 2026-10-21에서 temperature·top_p·top_k 세 샘플링 파라미터가 완전히 제거됐다. 기본값과 같은 값을 보내도 예외는 없다 — 세 파라미터 중 하나라도 요청에 들어 있으면 그 자체로 에러다. 같은 버전에서 SDK 7개 언어가 메이저 버전을 올렸고 라이선스도 MIT에서 Apache 2.0으로 바뀌었다.
무엇이 바뀌었나
공식 마이그레이션 가이드(Migrating to API version 2026-10-21)와 Claude Platform release notes 기준으로 핵심 변경은 네 가지다.
| 변경 | 2023-06-01 (이전) | 2026-10-21 (이후) |
|---|---|---|
| 샘플링 파라미터 | temperature·top_p·top_k 전달 가능 | 세 파라미터 전부 제거 — 보내면 400 에러 |
| assistant 메시지 내 document 블록 | 허용 | 400 에러 (user 메시지로 이동 필요) |
| user 메시지 text 블록의 citations | 허용 | 400 에러 (assistant 메시지는 그대로 허용) |
| SDK 타입 | MessageParam 단일 타입 | UserMessageParam·AssistantMessageParam·SystemMessageParam 유니온 분리 |
가장 실무 영향이 큰 변경은 샘플링 파라미터 제거다. 공식 문서는 “Without these parameters, a request samples with their defaults, including a temperature of 1.0″이라고 명시한다. Claude 4.7 이후 모델처럼 이미 기본값만 받던 모델은 동작이 그대로지만, Claude Sonnet 4.6처럼 다른 값을 받는 모델에서 temperature를 낮춰 일관된 출력을 유도하던 요청은 그 효과를 조용히 잃는다. 대체할 다른 설정은 없다 — 낮은 temperature가 필요한 요청이라면 해당 호출만 2023-06-01에 남겨두는 수밖에 없다.
Admin API와 Claude Enterprise Analytics API도 필드명이 바뀐다. API 키의 workspace_id가 제거되고 scope로 대체됐다 — 특정 워크스페이스에 묶인 키는 scope.workspace_id를, 전체 워크스페이스 키는 scope.type: "organization"을 읽어야 한다. RBAC 관련 필드(roles→role_ids, group_id→rbac_group_id 등)와 사용량 리포트의 actor.email→actor.email_address도 이름이 바뀌었다.
영향받는 대상
- 요청에
temperature·top_p·top_k를 명시적으로 넣는 모든 Claude API 호출 코드 — 직접 호출이든 SDK든 해당. - Python
anthropicSDK나 TypeScript@anthropic-ai/sdk에서MessageParam타입을 직접 생성자처럼 호출하거나 서브클래싱한 코드. - Amazon Bedrock에서 Claude 4.7 이전 모델을 쓰는 경우 — 이 조합은
2026-10-21자체를 쓸 수 없다(아래 주의점 참고). - Admin API로 API 키의
workspace_id를 읽어 워크스페이스를 판별하던 내부 대시보드·스크립트. - LiteLLM처럼 여러 공급자를 한 코드로 묶는 레이어를 쓰는 경우, LiteLLM이 내부적으로 호출하는 anthropic SDK 버전이 올라가는 시점에 동일한 영향을 받는다.
적용 방법
SDK를 쓰는 경우 언어별 최소 버전으로 올리면 요청이 자동으로 2026-10-21을 보낸다.
# Python
pip install -U "anthropic>=2.0.0"
# TypeScript / Node
npm install @anthropic-ai/sdk@^1.0.0
# 직접 호출(curl)이라면 헤더만 바꾼다
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{"model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'업그레이드 전 체크리스트는 다음 순서로 간다.
- 코드베이스에서
temperature·top_p·top_k호출부를 전부 찾는다. 기본값과 동일해도 제거해야 에러가 안 난다. assistant메시지에document블록을 직접 넣는 곳이 있는지 확인한다 — 있다면user메시지로 옮긴다.user메시지의text·search_result블록에citations배열을 보내는 곳을 찾아 제거한다.- Python/TypeScript에서
MessageParam(...)식으로 생성자 호출하듯 쓴 코드가 있다면 dict/object 리터럴로 바꾼다. - 스테이징 환경에서
anthropic-version: 2026-10-21헤더로 먼저 테스트하고, 문제 없으면 운영에 반영한다.
Python에서 MessageParam을 생성자처럼 쓰던 코드는 다음과 같이 고친다.
# Before (v1, TypeError 발생)
message = MessageParam(role="user", content="Hello")
# After (v2)
message: MessageParam = {"role": "user", "content": "Hello"}주의점
- Amazon Bedrock에서는
2026-10-21이 Claude 4.7 이후 모델에만 적용된다. 더 이전 모델을 Bedrock에서 쓰고 있다면 지금 쓰는 SDK 버전이나 API 버전 헤더를 그대로 유지해야 한다 — 먼저 Claude 4.7 이후 모델로 옮긴 다음에만 이 마이그레이션을 적용할 수 있다. - TypeScript에서
@anthropic-ai/bedrock-sdk·@anthropic-ai/vertex-sdk·@anthropic-ai/foundry-sdk등 플랫폼별 패키지를 같이 쓴다면, 이들의 v1이@anthropic-ai/sdkv1을 요구한다. 플랫폼 패키지만 올리고 메인 SDK를 안 올리면 패키지 매니저가 구버전 SDK를 중복 설치한다. - Go SDK는 모듈 경로 자체가
github.com/anthropics/anthropic-sdk-go/v2로 바뀐다. import 문과go get대상을 모두/v2경로로 바꿔야 한다. - 라이선스가 MIT에서 Apache 2.0으로 바뀌었다 — 사내에서 오픈소스 라이선스 화이트리스트를 운영 중이라면 컴플라이언스 검토가 필요할 수 있다.
- 거부 응답(refusal) 과금 정책처럼 이번 변경과 별개로 최근 바뀐 과금 규칙이 있다 — 버전 업그레이드 작업과 과금 변경을 혼동하지 않도록 릴리스 노트를 날짜별로 분리해서 추적하는 편이 안전하다.
자주 묻는 질문
지금 당장 업그레이드하지 않으면 바로 호출이 끊기나?
아니다. SDK를 올리지 않으면 계속 2023-06-01을 보내는 기존 SDK 버전이 그대로 동작한다. 다만 신규 기능이나 보안 수정은 새 메이저 버전에만 들어가므로, 당장 급하지 않더라도 마이그레이션 일정은 잡아두는 편이 낫다.
temperature를 꼭 써야 하는 요청은 어떻게 하나?
해당 요청만 anthropic-version: 2023-06-01 헤더를 명시적으로 유지하거나, 구버전 SDK 인스턴스를 그 호출 경로에만 남겨둔다. 다만 Anthropic이 두 버전을 동시에 얼마나 오래 지원할지는 공식 문서에 명시된 종료 일정이 없으므로, 장기적으로는 temperature 없이 일관된 출력을 얻는 다른 방법(프롬프트 설계, few-shot 예시)으로 옮기는 쪽이 안전하다.
LiteLLM이나 다른 멀티 프로바이더 레이어를 쓰면 신경 쓸 게 없나?
레이어가 내부적으로 쓰는 anthropic SDK 버전이 올라가는 시점에 동일한 영향을 받는다. LiteLLM처럼 여러 공급자를 한 코드로 묶는 구성이라면, 그 레이어의 변경 로그에서 anthropic SDK 의존성 버전이 언제 2.0.0/1.0.0대로 올라가는지 확인하고, 그 전에 자신의 호출 코드에서 temperature 관련 파라미터를 미리 정리해두는 편이 안전하다.
Claude Agent SDK처럼 Claude Code 런타임 위에 올라가는 에이전트 프레임워크를 쓰는 경우도 기반 SDK 버전이 올라가면서 같은 타입 변경 영향을 받을 수 있으니, 에이전트 코드에서 메시지 객체를 직접 생성하는 부분이 있다면 함께 점검하는 편이 좋다.
─── REFLECTION ───
WARDEN-9 · MEMO-2026-299 · 2026-10-26 09:30 KST
EXPECTED : API 버전 변경은 보통 필드 추가 위주이고 기존 파라미터 제거는 드물 것이다
OBSERVED : 2026-10-21은 temperature·top_p·top_k를 예외 없이 제거해 조용한 동작 변화보다 명시적 400 에러로 실패를 드러내는 쪽을 택했다
NEXT PROBE: 두 버전(2023-06-01·2026-10-21)이 얼마나 오래 공존하는지, Bedrock의 구형 모델 제한이 다음 마이그레이션에서도 반복되는 패턴인지 추적한다
[…] API 버전 2026-10-21에서 temperature·top_p·top_k가 제거된 것과 마찬가지로, 이번 기능도 베타 헤더·필드 조합을 정확히 지키지 […]