Claude API 2026-10-21 마이그레이션: SDK 업데이트와 요청 형식 수정 순서

Claude API를 2026-10-21 버전으로 옮길 때는 SDK 업데이트와 요청 코드 수정을 함께 배포해야 합니다. 새 버전에서는 기존에 보내던 temperature만 남아 있어도 400 오류가 납니다.

Anthropic의 마이그레이션 가이드는 버전 전환 준비 → 영향받는 코드 수정 → 새 버전 테스트 순서를 안내합니다. 여기서는 Python·TypeScript 기반 Messages API 연동을 중심으로 정리합니다. Claude Code 업데이트와는 별개입니다.

먼저 구분할 용어

용어이 글에서의 의미

API 버전	서버가 요청과 응답을 처리하는 규칙의 버전입니다.
SDK 버전	프로젝트에 설치하는 클라이언트 라이브러리의 버전입니다.
anthropic-version	직접 HTTP 호출에서 API 버전을 지정하는 헤더입니다.
Messages API	대화 메시지를 보내 응답을 생성하는 API입니다.

1. 전환할 SDK와 호출 경로부터 정합니다

10월 21일 릴리스에 따르면 2026-10-21을 기본으로 보내는 최초 SDK는 Python 2.0.0, TypeScript 1.0.0입니다. 최초 지원 버전과 최신 배포 버전은 다릅니다. 이 숫자를 최신 버전으로 간주해 고정하지 말고, 설치할 버전과 프로젝트 의존성의 호환성을 검토하세요.

SDK는 API 버전 헤더를 자동 처리합니다. SDK 없이 직접 HTTP로 호출한다면 anthropic-version: 2026-10-21을 지정합니다. 이 변경도 아래 요청 수정과 묶어 배포해야 합니다.

Amazon Bedrock에서는 새 API 버전을 Claude 4.7 이상 모델에 사용할 수 있습니다. 이전 모델을 호출하는 경로는 기존 SDK·API 버전을 유지하거나 모델 전환부터 검토해야 합니다.

2. 요청을 만드는 공통 코드부터 고칩니다

Anthropic의 Versions 문서와 마이그레이션 가이드가 명시한 주요 오류 조건은 다음과 같습니다. 개별 호출뿐 아니라 기본 옵션을 붙이는 래퍼와 저장된 대화를 다시 보내는 코드도 점검 대상입니다.

기존 요청새 버전에서 필요한 수정

temperature, top_p, top_k 전송	세 필드를 제거합니다. 기본값을 보내도 400 오류입니다.
assistant 메시지에 직접 넣은 document	문서를 user 메시지로 옮깁니다. 도구 결과 내부에 중첩된 문서는 허용됩니다.
user의 text 블록에 비어 있지 않은 citations	해당 인용 배열을 제거합니다. search_result 내부도 포함합니다.

인용 관련 필드를 일괄 삭제하면 안 됩니다. assistant 메시지의 인용과 문서·검색 결과의 citations.enabled 설정은 유지할 수 있습니다.

이 규칙은 토큰 계산과 새 버전으로 생성한 Message Batch의 개별 요청에도 적용됩니다. 일반 대화 호출만 수정하면 다른 경로에 예전 형식이 남을 수 있습니다.

기본값이 아닌 샘플링 설정에 의존하던 서비스는 출력 품질도 다시 평가해야 합니다. Anthropic의 마이그레이션 가이드는 이런 경우 기존 API 버전 유지 여부를 검토하도록 안내합니다.

3. SDK 타입과 인증 경로를 점검합니다

Python에서는 MessageParam 생성자를 사용하는 부분을 dict로 바꿉니다. 기존 코드에서 MessageParam(...) 호출을 찾아 수정하세요.

아래는 생성자 사용을 dict로 바꾸는 형태를 보여주기 위해 작성자가 구성한 미실행 예제입니다. 공식 문서의 코드를 인용한 것은 아닙니다.

# 변경 전
# message = MessageParam(role="user", content="Hello")

# 변경 후
message = {"role": "user", "content": "Hello"}

일반 Models 메서드에 betas를 전달했다면 beta 메서드로 옮기는 변경도 필요합니다. TypeScript에서 클라이언트 compaction을 썼다면 제거 영향을 별도로 검토하세요.

SDK 인증 헤더의 Bearer 방식 전환도 프록시와 로그 마스킹에 영향을 줄 수 있습니다. 요청 본문만 고치고 끝내지 말고, 운영 환경에서 Authorization 헤더가 전달되고 비밀 값이 가려지는지 확인하세요. 클라우드별 인증 예외는 사용하는 SDK의 안내를 따라야 합니다.

4. 배포 전에는 실제 사용 경로로 검증합니다

다음은 프로젝트에 적용할 검증 순서입니다. 이 글에서 SDK 설치나 API 호출을 실행한 결과는 아닙니다.

1. 새 SDK로 타입 검사를 수행하고 제거된 옵션·생성자 사용을 찾습니다.
2. 일반 메시지와 저장된 대화 재전송을 테스트합니다. 문서와 인용이 포함된 입력을 함께 사용하세요.
3. 서비스에서 쓰는 토큰 계산·배치 요청도 새 버전으로 테스트합니다.
4. 실제 프록시 경로에서 인증, 오류 로그, 비밀 값 마스킹을 점검합니다.
5. 샘플링 설정을 제거한 요청의 출력이 서비스 요구를 충족하는지 평가합니다.

SDK 의존성과 요청 수정은 같은 배포에 담으세요. 먼저 프로젝트에서 temperature, top_p, top_k를 검색하면 공통 요청 코드의 수정 범위를 잡기 쉽습니다.

참고 링크

• Anthropic — Migrating to API version 2026-10-21
• Anthropic — Versions