- 2026-10-21에 Claude API의 새로운 API 버전
2026-10-21
그리고 이를 기본값으로 전송하는 Python SDK 2.0.0이 출시되었습니다. v1.17.0과 v2.5.0에서 동일한 코드를 각각 한 번씩 실행하여 7가지 작성 방식을 비교했습니다. v2에서는 API 키 전달 방식(
x-api-key
→Authorization: Bearer),
MessageParam(...) 호출, models.list(betas=...),
api_key와 auth_token의 병용 사용 등으로 동작이 변경되었습니다. Sonnet 4.6에 extra_body로 보낸 temperature=0.2는 v1에서는 통했지만, v2에서는 API 측에서 400 에러가 발생했습니다. 하지만 v2부터 API 버전 2023-06-01을 지정하자 동일한 temperature 값은 통과했습니다. 모두 각 1회 결과이므로, 마이그레이션 시에는 자신의 코드를 v2로 실제로 실행하여 확인하는 것이 필요합니다.
2026-10-21에 Claude API의 API 버전 2026-10-21
이 출시되었습니다(릴리스 노트). API 버전은 요청의 anthropic-version 헤더로 지정하는 값입니다. 이전까지는 2023-06-01이 사용되어 왔습니다.
같은 날, 기본값으로 2026-10-21을 전송하는 SDK도 출시되었습니다. Python에서는 anthropic 2.0.0입니다(CHANGELOG). 라이선스 또한 2.0.0부터 MIT가 아닌 Apache 2.0으로 변경되었습니다(마이그레이션 가이드).
마이그레이션 가이드의 변경점 중, Python으로 작성된 일반적인 앱과 관련성이 높아 보이는 내용은 다음과 같습니다.
| 변경 | 어느 쪽의 변경인가 | 내용 (마이그레이션 가이드에서 발췌) |
|---|
| 샘플링 파라미터 | API | temperature ・top_p ・top_k를 전송할 경우, 기본값에서도 400 에러가 발생함 |
어시스턴트의 document 블록 | API | assistant 메시지에 직접 document 블록을 넣으면 400 에러가 발생함 |
사용자 메시지의 citations | | |
| API | user 메시지의 text 블록에 빈 것이 아닌 citations가 있을 경우 400 에러가 발생함 | |
MessageParam | SDK | 역할별 타입의 union(‘어떤 하나의 타입을’ 나타내는 타입)이 됩니다. MessageParam(...)이라고 호출하면 TypeError가 발생합니다. |
| 베타가 아닌 Models의 메서드 | SDK |
| API 키 헤더 | SDK | X-Api-Key가 아닌 Authorization: Bearer <key>로 전송해야 합니다. |
| 인증 정보는 1개만 | SDK | api_key와 auth_token 등을 2가지 이상 전달하면 ValueError가 발생합니다. |
'API' 행은 API 버전 2026-10-21을 보냈을 때 API가 반환하는 결과의 변경입니다. 'SDK' 행은 SDK를 업그레이드할 때 바뀌는 내용입니다.
본 기사에서는 v1의 마지막 버전(1.17.0)과 작성 시점의 최신 버전(2.5.0, 2026-11-04 공개)에 동일한 코드를 전달하여 표의 5가지 변경점을 확인합니다. API 관련 3가지는 '샘플링 파라미터'만 (또한 temperature를 extra_body로 전송하는 경우에 한해), SDK 관련 4가지는 모두입니다.
동일한 main.py 파일을 anthropic 1.17.0 환경(.venv-v1)과 2.5.0 환경(.venv)에서 각각 1회 실행합니다. 7가지 작성 방식을 순서대로 시도하며 성공 여부나 어떤 에러가 발생하는지 기록했습니다.
API를 호출하는 것은 1, 3, 4, 5, 7번입니다 (4번은 v2에서는 API를 호출하기 전에 SDK가 에러를 발생시킵니다). 모델은 평소에 저렴한 claude-haiku-5-5로 설정했습니다. temperature 확인(3번과 7번)만은, temperature
값의 값을 변경할 수 있는 claude-sonnet-4-6을 사용합니다. 비용은 1센트 미만으로 예상됩니다(요금).
- OS: macOS 27.2 (Apple M3 / 24GB)
- Python: 3.12.15
- 주요 라이브러리: anthropic==1.17.0 (
.venv-v1) 및 anthropic==2.5.0 (.venv), python-dotenv==1.2.4 - 모델: claude-haiku-5-5 (3번과 7번만 claude-sonnet-4-6) - 실행일: 2026-11-07
cd code
uv venv --python 3.12 .venv-v1
uv pip install --python .venv-v1 -r requirements-v1.txt
...
run.sh는 main.py를 두 개의 환경에서 순차적으로 실행하고, outputs/run.log에 저장합니다.
main.py의 전체 내용입니다. 7가지 작성 방식을 check()로 하나씩 실행하며, 예외가 발생하면 종류와 메시지를 표시합니다. 전송된 헤더는 HTTP 클라이언트의 이벤트 후크(요청을 보내기 직전에 호출되는 함수)에서 기록됩니다(API 키 값은 표시하지 않습니다). extra_body는 전달한 dict를 그대로 요청 JSON에 추가하는 SDK 메커니즘입니다. SDK 인자에 없는 항목도 전송할 수 있습니다.
"""v1로 작성된 일반적인 코드를 anthropic v1과 v2 모두에서 실행하여 어디가 바뀌는지 확인한다.
같은 파일을 .venv-v1 (anthropic 1.17.0)와 .venv (anthropic 2.5.0)에서 실행한다.
확인할 변경 사항은 공식 마이그레이션 가이드에 나와 있는 내용:
...
"""
outputs/run.log의 전체 내용입니다.
# run at: 2026-11-07 09:52:07 JST
################ main.py with .venv-v1
Python 3.12.15 / Darwin arm64
...
7가지 작성 방식의 결과를 요약하면 다음과 같습니다(각 1회).
| # | 작성 방식 | v1.17.0 | v2.5.0 |
|---|
| 1 | 일반 요청 | 성공. anthropic-version: 2023-06-01, 키는 x-api-key로 전송 | 성공. anthropic-version: 2026-10-21, 키는 Authorization: Bearer로 전송 |
| 2 | MessageParam(role=..., content=...) | 성공 (dict가 생성됨) | TypeError: Cannot instantiate typing.Union |
| 3 | Sonnet 4.6에 temperature=0.2를 extra_body로 전송 | 성공 | API가 400 (temperature: Extra inputs are not permitted) |
| 4 | client.models.list(betas=...) | 성공 | TypeError (betas를 수신하지 않음) |
| 5 | client.beta.models.list(betas=...) | 성공 | 성공 |
| 6 | api_key와 auth_token을 모두 전달 | 성공 (클라이언트 생성됨) | ValueError: Pass at most one of ... |
| 7 | 3번과 동일한 것을 anthropic-version: 2023-06-01로 전송 | 성공 | 성공 |
v1에서 extra_body를 사용해 전송했던 temperature는 v2에서는 API에 의해 차단되었습니다. Python SDK는 1.0.0 (2026-08-20) 버전부터 temperature, top_p, top_k 인자를 제거했습니다. 이때 SDK의 MIGRATION.md에는 이들을 아직 사용하는 구형 모델을 위해, extra_body로 전달하는 작성 방식을 안내하고 있습니다. 3번은 그 예시와 같은 형태입니다 (claude-sonnet-4-6)
에 temperature=0.2
)ト입니다. 2023-06-01
을 보내는 v1에서는 성공했지만, 2026-10-21
을 보내는 v2에서는 400이 되었습니다. SDK의 인수는 아니기 때문에, v2로 올려도 타입 에러가 나지는 않으며, 실행해 보고 나서야 멈추게 됩니다. 이 400이 SDK 버전 때문인지, API 버전에 의한 것인지를 구분하기 위해, 7번에서는 v2에서 anthropic-version: 2023-06-01
을 지정하여 동일한 것을 보냈습니다. 이쪽은 성공했습니다. 이번 한 번의 결과만으로는, 400을 결정했던 것은 API 버전이었습니다. 마이그레이션 가이드 설명과도 일치합니다(Sampling parameters are removed). 이번 결과와 마이그레이션 가이드에 따르면, v1에서 extra_body
를 사용하여 temperature
를 낮추던 코드는, v2로 올리면 멈출 것으로 생각됩니다. 마이그레이션 가이드에서는 이러한 파라미터들을 제외하거나, 해당 요청만 2023-06-01
으로 보내도록 작성되어 있습니다(7번에서 확인한 형태입니다).
API 키의 헤더가 바뀐다. 1번에서는 v2 SDK가 API 키를 Authorization: Bearer
로 보내고 있었습니다. SDK만 사용하는 경우라면, 코드를 바꿀 필요는 없었습니다. 다만, 중간에 프록시나 게이트웨이를 두어 X-Api-Key
를 읽고 있다면, 그쪽을 수정해야 합니다(마이그레이션 가이드).
2・4・6번은 가이드대로 고칠 수 있다. 2번은 dict로 작성하고, 4번은 client.beta.models
를 사용하며(5번에서 성공 확인), 6번은 인증 정보를 하나로 통일하는 방법이 마이그레이션 가이드에 나와 있습니다.
anthropic
1.17.0과 2.5.0으로 동일한 코드를 각각 한 번씩 실행했을 때, 7가지 작성 방식 중 5가지(1・2・3・4・6번)에서 결과가 달랐습니다. 1번은 에러는 나지 않았지만, 보내는 헤더(API 버전과 API 키 전송 방식)만 바뀌었습니다. 가장 주의해야 할 부분은
temperature
이었습니다. Sonnet 4.6에 extra_body
로 보낸 temperature=0.2
는 v1(2023-06-01
)에서는 통했지만, v2(2026-10-21
)에서는 400이 되었습니다. 타입 에러가 아니어서 실행해 보고 나서야 알 수 있습니다. 이번에 시도한 것은 마이그레이션 가이드 변경의 일부였으며, 각각 한 번씩만 진행했습니다. 마이그레이션 할 때는 자신의 코드를 v2로 실제로 작동시켜 확인하는 것이 필요합니다.
- Migrating to API version 2026-10-21 — Anthropic
- Claude Platform release notes — Anthropic (API 버전 2026-10-21과 SDK 항목은 2026-10-21)
- anthropic-sdk-python CHANGELOG.md — Anthropic (GitHub. 2.0.0은 2026-10-21, 2.5.0은 2026-11-04)
- anthropic-sdk-python MIGRATION.md — Anthropic (GitHub)
- anthropic (PyPI) — PyPI
- Pricing — Anthropic
