클로드 API로 만든 자동화가 있다면 이번 주에 pip install -U anthropic을 조심해야 합니다. Anthropic이 10월 21일 클로드 API의 새 버전 2026-10-21을 내놓았고, 같은 날 나온 파이썬 SDK 2.0.0부터 요청에 이 버전이 붙어 나갑니다. 2023년 6월 1일 버전 이후 처음 바뀐 API 버전입니다. 공식 마이그레이션 안내(2026-10-22 확인)를 기준으로, 같은 파이썬 코드 3개를 SDK 세 버전으로 연습 서버에 돌려 어디서 멈추는지 확인한 기록입니다.
- 무엇이 바뀌었나: API 버전 2026-10-21에서 temperature·top_p·top_k가 없어졌습니다(보내면 400 오류). 새 SDK는 이 버전을 기본으로 보내고, 키를
Authorization: Bearer헤더로 보냅니다. - 누구에게: 파이썬 anthropic 패키지를 2.0.0 이상으로 올리는 사람. 특히 SDK 1.x 안내대로
extra_body={"temperature": 0}로 옮겨 둔 코드는 2.x에서 다시 400 오류가 납니다. - 지금 할 일: 올리기 전에 코드에서 temperature·top_p·top_k와
MessageParam(...)호출을 찾아 고칩니다. SDK를 안 올리면 지금 코드는 옛 버전(2023-06-01)으로 그대로 갑니다.
결과부터 보기: 같은 코드, SDK 버전만 바꿔 9번
리뷰 한 줄을 긍정·부정으로 나누는 짧은 스크립트 3개를 준비했습니다. 하나는 temperature를 그대로 쓰는 옛 코드, 하나는 SDK 1.x 안내대로 temperature를 extra_body로 옮긴 코드, 하나는 새 버전에 맞춘 코드입니다. 각각을 anthropic 0.125.0(0.x 마지막), 1.17.0(1.x 마지막), 2.1.0(최신)으로 실행했습니다.
직접 눌러 보기: 클로드 API 새 버전 점검기. 내 코드를 붙여 넣으면 2026-10-21과 새 SDK에서 걸리는 줄을 찾아 줍니다. 이번에 돌린 코드 3개를 예시 버튼으로 넣어 볼 수 있습니다.
직접 실행 확인한 날짜 2026-10-22
- 실행 환경
- macOS 26.1 · Python 3.13 · anthropic 0.125.0 / 1.17.0 / 2.1.0 (가상환경 3개)
- 확인 방법
- 실제 API 대신 공식 마이그레이션 안내의 temperature 400 규칙을 넣은 연습 서버. 받은 요청의 버전·키 헤더를 기록. 실제 API의 오류 문구는 확인하지 않음
- 비용
- API 버전 변경과 SDK 업데이트 자체는 무료. 요금표는 바뀌지 않음
- 라이선스
- 새 SDK·CLI는 Apache 2.0(이전 버전은 MIT 그대로)

옛 코드는 0.125.0에서만 돌았습니다. 1.17.0에서는 서버에 닿기도 전에 TypeError: Messages.create() got an unexpected keyword argument 'temperature'(temperature라는 인자를 모른다)로 멈췄습니다. 파이썬 SDK는 이미 1.0.0(8월 20일)에서 이 세 인자를 뺐고, 옛 모델에 꼭 필요하면 extra_body로 넘기라고 안내했습니다. 2.1.0에서는 그보다 앞의 MessageParam(role=..., content=...) 줄에서 TypeError: Cannot instantiate typing.Union(묶음 타입은 만들 수 없다)으로 멈췄습니다.
더 눈여겨볼 것은 두 번째 코드입니다. 1.x 안내대로 옮긴 extra_body={"temperature": 0}은 0.125.0과 1.17.0에서 잘 돌았습니다. 2.1.0으로 올리자 같은 코드가 요청을 anthropic-version: 2026-10-21로 보냈고, 연습 서버는 문서 규칙대로 400을 돌려줬습니다. 화면의 오류 문구는 연습 서버가 만든 것이라 실제 API 문구와 다를 수 있습니다. 연습 서버 기록에는 키 헤더도 X-Api-Key에서 Authorization: Bearer로 바뀐 것이 남았습니다.
바뀐 것 5가지
1. temperature·top_p·top_k를 보내면 400 오류
무엇이 2026-10-21 버전으로 보낸 메시지 요청과 배치 요청에 이 세 값이 있으면, 기본값이어도 400 오류입니다. 모든 모델에 해당합니다. 누구에게 결과를 일정하게 하려고 temperature=0을 넣어 둔 사람. 공식 안내에 따르면 클로드 4.7 이후 모델은 원래 기본값만 받아서 빼도 결과가 달라지지 않습니다. 소넷 4.6처럼 다른 값을 받던 모델은 낮춰 둔 효과가 사라지고, 대신할 설정은 없습니다. 해 보는 법 세 값을 지웁니다. 옛 모델에서 꼭 필요한 요청만 버전을 2023-06-01로 남깁니다(아래 3단계).
2. SDK가 보내는 버전이 2026-10-21로
무엇이 예전 SDK는 모든 요청에 anthropic-version: 2023-06-01을 붙였습니다. 새 SDK(파이썬 2.0.0, 타입스크립트 1.0.0 등)는 2026-10-21을 붙입니다. SDK 없이 cURL로 부르면 헤더 값을 직접 바꿀 때까지 옛 버전 그대로입니다. 누구에게 SDK를 올리는 모든 사람. 해 보는 법 아래 표의 버전으로 올리면서 1번·4번을 함께 고칩니다.
| 언어 | 처음으로 2026-10-21을 보내는 버전 |
|---|---|
파이썬 anthropic | 2.0.0 |
타입스크립트 @anthropic-ai/sdk | 1.0.0 |
자바 anthropic-java | 3.0.0 |
고 anthropic-sdk-go/v2 | 2.0.0 |
C# Anthropic | 13.0.0 |
| PHP·루비 | 1.0.0 · 2.0.0 |
ant CLI | 2.0.0 |
아마존 베드록에서는 2026-10-21을 클로드 4.7 이후 모델에만 쓸 수 있습니다. 베드록에서 더 오래된 모델을 부르면 지금 SDK 버전에 머물라고 공식 안내가 적고 있습니다.
3. API 키가 Authorization 헤더로
무엇이 새 SDK와 CLI는 키를 X-Api-Key 대신 Authorization: Bearer <키>로 보냅니다. 클로드 API는 두 헤더를 다 받습니다. 누구에게 회사 프록시·게이트웨이가 X-Api-Key에서 키를 읽는 경우, 또는 코드에서 extra_headers={"X-Api-Key": ...}로 키를 바꿔 끼우던 경우. 새 SDK에서는 키가 두 개 다 나갑니다. 해 보는 법 프록시가 Authorization을 읽게 고치거나, 요청마다 다른 키는 extra_headers={"Authorization": f"Bearer {키}"}로 넘깁니다(공식 안내 기준). API에 바로 보내는 코드는 손댈 것이 없습니다.
4. 파이썬 MessageParam(…)을 부르면 TypeError
무엇이 파이썬 SDK 2.0에서 MessageParam이 역할별 타입(UserMessageParam·AssistantMessageParam·SystemMessageParam)의 묶음이 됐습니다. 이름을 타입 표시에 쓰는 것은 그대로 되지만, 함수처럼 부르면 오류입니다. 누구에게 MessageParam(role="user", content=...)로 메시지를 만들던 사람. 해 보는 법 {"role": "user", "content": ...} 같은 dict로 씁니다. 처음부터 dict로 쓰던 코드는 바꿀 것이 없습니다.
5. 그 밖에: 라이선스, 문서·인용 규칙, 관리용 API 필드
새 SDK와 CLI는 Apache 2.0 라이선스로 바뀌었습니다. 코드는 고칠 것이 없고, 의존성 라이선스 목록만 고칩니다. assistant 메시지 안에 document 블록을 바로 넣거나, user 메시지의 글 블록에 citations(인용)를 붙이면 400 오류가 납니다. 관리용 Admin API와 엔터프라이즈 분석 API에서는 roles→role_ids, actor.email→actor.email_address처럼 옛 필드 이름이 응답에서 빠졌습니다. 회사 계정을 관리하는 코드가 아니면 해당하지 않습니다.
내 코드가 걸리는지 확인하고 고치기
1단계. 지금 SDK 버전 확인 (약 1분)
이 단계에서는 프로젝트에 깔린 SDK 버전을 봅니다. 프로젝트 폴더의 터미널에서 실행합니다(가상환경을 쓰면 켠 뒤).
pip show anthropic
Name: anthropic
Version: 2.1.0
Summary: The official Python library for the anthropic API
(이하 생략)
이렇게 나오면 Version이 2.으로 시작하면 이미 새 버전으로 요청이 나가고 있습니다. 1.이나 0.으로 시작하면 아직 2023-06-01입니다. 올리기 전에 2단계를 먼저 합니다.
WARNING: Package(s) not found가 나오면: 이 환경에는 SDK가 없습니다. 실제로 스크립트를 돌리는 가상환경을 켜고 다시 실행합니다.
2단계. 걸리는 줄 찾기 (약 1분)
이 단계에서는 고칠 곳을 찾습니다. 같은 폴더에서 아래 명령을 실행하거나, 코드를 점검기에 붙여 넣습니다.
grep -rnE "temperature|top_p|top_k|MessageParam\(|[Xx]-[Aa]pi-[Kk]ey" --include="*.py" --exclude-dir=".venv" --exclude-dir="venv" .
v1_review.py:8: extra_body={"temperature": 0}, # SDK 1.x 안내대로 옮긴 온도 설정
old_review.py:5:messages = [MessageParam(role="user", content="리뷰: 배송이 빨라요. 긍정/부정 한 단어로")]
old_review.py:9: temperature=0,
이렇게 나오면 성공 나온 줄이 고칠 곳입니다. 새 버전에 맞춘 new_review.py는 한 줄도 나오지 않았습니다. 아무것도 안 나오면 SDK를 올려도 이 항목들에는 걸리지 않습니다.
3단계. 고치고 새 SDK로 시험하기 (약 3분)
이 단계에서는 찾은 줄을 고친 뒤 새 SDK로 돌려 봅니다. temperature 줄은 지우고, MessageParam(...)은 dict로 바꿉니다. 고친 new_review.py입니다.
import anthropic
from anthropic.types import MessageParam
client = anthropic.Anthropic() # ANTHROPIC_API_KEY 환경 변수에서 키를 읽음
messages: list[MessageParam] = [{"role": "user", "content": "리뷰: 배송이 빨라요. 긍정/부정 한 단어로"}]
reply = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=50,
messages=messages,
)
print("답:", reply.content[0].text)
결과를 일정하게 해야 해서 temperature를 꼭 남겨야 하는 요청이면, 그 클라이언트만 옛 버전으로 보냅니다. 공식 안내가 “그 요청은 2023-06-01에 두라”고 적은 방법입니다.
import anthropic
# 온도 설정이 꼭 필요한 요청만 옛 API 버전(2023-06-01)으로 보냄
client = anthropic.Anthropic(default_headers={"anthropic-version": "2023-06-01"})
reply = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=50,
messages=[{"role": "user", "content": "리뷰: 배송이 빨라요. 긍정/부정 한 단어로"}],
extra_body={"temperature": 0},
)

이렇게 나오면 성공 두 파일 모두 답: 긍정을 받았습니다. 고친 코드는 2026-10-21로, 옛 버전을 지정한 코드는 2023-06-01로 들어왔습니다. 실제 API에서는 키를 넣고 요청 한 번으로 같은 확인을 합니다.
pip install -U anthropic뒤에 문제가 생기고 당장 고칠 시간이 없으면:pip install "anthropic<2"로 되돌립니다. 그러면 요청이 다시 2023-06-01로 나갑니다.- 클로드 코드를 쓰면: 2.1.307 업데이트에 클로드 API 코드를 2026-10-21로 옮기는
/claude-api api-version명령이 들어갔습니다(변경 기록 기준, 이번에는 쓰지 않음). claude-api 스킬이 옛 코드를 어떻게 고치는지는 클로드 API 모델 바꾸기 글에 있습니다.
이번 실험의 코드 3개, 옛 버전 지정 예시, 연습 서버, 실행 스크립트는 실습 재료(zip)에 넣었습니다. 가짜 키로 내 컴퓨터의 연습 서버에만 요청하니 실제 키가 필요 없습니다.
한계와 주의할 점
- 실제 API가 아니라, 공식 안내의 temperature 400 규칙만 넣은 연습 서버로 돌렸습니다. SDK 쪽 오류(TypeError)와 SDK가 보내는 버전·키 헤더는 실제로 확인한 것이고, API 쪽 400 응답은 문서 기준입니다.
- 파이썬 SDK는 1.0부터 Python 3.10 이상이 필요합니다. 그보다 오래된 파이썬이면 SDK를 올리기 전에 파이썬부터 올려야 합니다.
- 파이썬 SDK만 돌려 봤습니다. 타입스크립트·고·자바 등의 변경은 공식 안내 기준이고, 언어마다 바뀐 것이 따로 있습니다(예: 고는 1.25 이상 필요, 타입스크립트는 베드록·버텍스 패키지도 1.0으로 함께 올려야 함).
- 공식 문서에 2023-06-01 버전을 언제까지 쓸 수 있는지는 적혀 있지 않습니다(2026-10-22 확인). Anthropic은 가능하면 최신 버전을 쓰라고 권합니다.
자주 묻는 질문
SDK를 안 올리면 아무 일도 없나요?
예전 SDK는 계속 2023-06-01을 보냅니다. 이번에도 1.17.0은 2023-06-01로 보냈고, temperature를 extra_body로 넘긴 코드가 그대로 돌았습니다. 이 버전을 언제까지 쓸 수 있는지는 한계 절에 적었습니다.
temperature를 빼면 답이 매번 달라지나요?
공식 안내에 따르면 클로드 4.7 이후 모델은 이미 기본값만 받아 왔기 때문에, 빼도 지금과 같게 동작합니다. 소넷 4.6처럼 낮은 값을 받던 모델에서는 그 효과가 사라집니다. 형식을 일정하게 받고 싶다면 구조화 출력(JSON 스키마)으로 모양을 고정하는 방법이 있습니다.
요금도 바뀌었나요?
API 버전과 SDK 변경에는 요금 이야기가 없습니다. 요금은 모델별 가격표를 따릅니다. 구독과 API 요금 차이는 클로드 요금제 정리를 보세요.
cURL로 직접 부르는데 고칠 것이 있나요?
헤더를 anthropic-version: 2023-06-01로 보내는 동안은 없습니다. 2026-10-21로 바꿀 때 temperature·top_p·top_k를 함께 지우면 됩니다.
출처
API 버전 2026-10-21 마이그레이션 안내, API 버전 목록, 클로드 플랫폼 변경 기록(10월 21일), 파이썬 SDK 변경 기록, 파이썬 SDK 1.0 이전 안내, 클로드 코드 변경 기록(2.1.307) (모두 2026-10-22 확인)