Claude API 2026-10-21 버전: 변경 사항과 안전한 업그레이드 방법

Claude API 버전 2026-10-21은 2023-06-01 이후 처음 나온 새로운 anthropic-version 값입니다. 이 버전은 Messages API에 세 가지 호환성 깨는 변경을 적용합니다. temperature, top_p, top_k는 이제 400 오류를 반환하고, assistant 메시지의 document 블록은 400을 반환하며, user 메시지의 text 블록에 있는 citations도 400을 반환합니다. 또한 여러 Admin API 및 Enterprise Analytics API 필드의 이름이 변경됩니다. anthropic-version: 2026-10-21을 전송하거나 새로운 SDK 메이저 버전(Python 2.0.0, TypeScript 1.0.0, Go 2.0.0 등)으로 업그레이드하여 옵트인할 수 있습니다.

문제는 대부분의 팀이 SDK를 업그레이드하면서 "의도치 않게" 새 버전으로 이동하게 된다는 점입니다. 메이저 버전을 넘는 일상적인 pip install -U anthropic 또는 npm update 한 번이면 모든 요청이 한꺼번에 2026-10-21로 전환됩니다. 이 가이드는 Anthropic이 문서화한 모든 변경 사항을 나열하고, 실제 코드에서 어떤 변경이 문제를 일으키는지 보여주며, 안전한 업그레이드 순서를 제시합니다.

anthropic-version 헤더란 무엇인가?

anthropic-version 헤더는 응답으로 받는 Claude API의 형태를 고정하는 필수 요청 헤더입니다. 하나의 버전 내에서 Anthropic은 기존 입력 및 출력 파라미터를 안정적으로 유지하지만, 선택적 입력, 새로운 출력 값, 스트리밍 이벤트 유형과 같은 새로운 열거형 변형, 그리고 새로운 오류 조건을 추가할 수 있습니다. 호환성을 깨는 변경은 새로운 버전 날짜와 함께만 도입됩니다.

버전 관리 페이지에 따르면 세 가지 버전이 존재합니다:

공식 SDK를 사용한다면 헤더를 직접 설정할 필요가 없습니다. 각 SDK 메이저 버전은 해당 메이저 버전이 출시될 당시의 최신 버전을 전송합니다. 그래서 대부분의 코드베이스에서 SDK 업그레이드와 API 버전 업그레이드는 같은 사건입니다.

Claude API 2026-10-21 호환성 깨는 변경 사항

이 변경 사항들은 POST /v1/messages, 토큰 카운팅, 그리고 2026-10-21로 생성된 Message Batch 내의 모든 요청에 적용됩니다.

1. temperature, top_p, top_k가 제거됨

가장 많은 사람이 마주칠 변경입니다. temperature, top_p, top_k를 전송하는 모든 요청은 모든 모델에서 400 오류를 반환하며, 기본값을 전송하더라도 마찬가지입니다. 설정 파일에 남아 있는 temperature: 1.0 하나만으로도 호출이 실패합니다.

출력 품질에 미치는 영향은 모델에 따라 다릅니다:

• Claude 4.7 이상은 이미 기본 샘플링 값만 허용하므로, 파라미터를 제거해도 샘플링 방식에는 아무 변화가 없습니다.
• 다른 값을 허용하는 이전 모델(예: Claude Sonnet 4.6)은 temperature를 낮춰서 얻던 효과를 잃게 됩니다. 마이그레이션 가이드는 이를 분명히 밝힙니다: 이를 대체하는 다른 설정은 없습니다.

요청이 정말로 기본값이 아닌 값에 의존한다면, Anthropic은 두 가지 선택지를 제공합니다: 전송을 중단하거나, 해당 특정 요청을 2023-06-01에 유지하는 것입니다.

2. assistant 메시지의 document 블록은 400을 반환함

일부 앱은 assistant 턴에 document 블록을 직접 넣어 대화 기록을 재생합니다. 2026-10-21에서는 이것이 거부됩니다. 문서를 user 메시지로 옮기세요. 다른 블록 안에 중첩된 문서(예: Claude가 반환한 웹 페치 도구 결과)는 여전히 허용됩니다.

3. user 메시지의 citations는 400을 반환함

user 메시지에서 비어 있지 않은 citations 배열을 가진 text 블록은 이제 실패하며, 여기에는 search_result 블록 내부의 텍스트도 포함됩니다. 해당 블록에서 citations를 제거하세요. 다시 전송하는 Claude 자신의 assistant 응답에 있는 인용은 여전히 괜찮으며, 문서와 검색 결과에 대한 "citations": {"enabled": true}도 마찬가지입니다.

4. Admin API 및 Enterprise Analytics 필드 이름 변경

응답에는 더 이상 이전 필드 이름이 포함되지 않습니다:

API 키 변경이 미묘한 부분입니다. 2023-06-01에서는 Default Workspace에 바인딩된 키와 모든 워크스페이스 키 모두에 대해 workspace_id가 null이었습니다. 2026-10-21에서는 scope.workspace_id에 Default Workspace의 실제 ID가 들어가고, 모든 워크스페이스 키는 workspace_id 없이 scope: {"type": "organization"}을 갖습니다. 대시보드가 null을 "Default Workspace"로 처리했다면, 업그레이드 후 키에 잘못된 레이블을 붙이게 됩니다.

2026-10-21을 전송하는 SDK 버전

Anthropic은 2026년 10월 21일에 새로운 SDK 메이저 버전을 출시했으며, 릴리스 노트에 따르면 각 버전은 기본적으로 2026-10-21을 전송합니다:

새 메이저 버전에는 API 버전과 전혀 무관한 변경 사항도 있습니다:

• API 키가 X-Api-Key 대신 Authorization: Bearer <key>로 전송됩니다. Claude API는 둘 다 허용하지만, X-Api-Key를 읽는 프록시, 게이트웨이, 로그 필터 또는 테스트 스텁은 더 이상 키를 볼 수 없습니다.
• Text Completions가 제거되었습니다. TypeScript, Go, Java, Ruby SDK와 CLI에서 제거되었습니다. Messages API를 사용하세요.
• 비베타 Models 메서드에서 betas가 사라졌습니다. 대신 client.beta.models를 호출하세요.
• 타입이 지정된 SDK에서 MessageParam은 역할별로 하나의 타입을 가진 유니온입니다. 따라서 일부 타입 주석을 업데이트해야 합니다.
• Go는 /v2로 끝나는 새로운 임포트 경로가 필요합니다. 그리고 Bedrock, Vertex, Foundry, AWS 또는 Google Cloud 패키지를 사용하는 TypeScript 사용자는 같은 업그레이드에서 해당 패키지를 v1로 옮겨야 합니다. 그렇지 않으면 패키지 관리자가 코어 SDK의 더 오래된 사본을 두 번째로 설치합니다.
• 라이선스가 MIT에서 Apache 2.0으로 변경되었습니다.

무엇보다 먼저 현재 메이저 버전을 고정하세요. 그러면 의존성 봇이 스프린트 도중에 업그레이드하는 것을 막을 수 있습니다.

Amazon Bedrock 예외

Amazon Bedrock에서 2026-10-21은 Claude 4.7 이상 모델에서만 작동합니다. 여전히 Opus 4.6이나 그 이전 모델을 호출한다면, 현재 SDK 버전을 유지하거나 현재 헤더를 계속 전송하고, 먼저 모델을 전환하세요.

Claude API 버전 2026-10-21로 안전하게 업그레이드하는 방법

마이그레이션 가이드의 순서는 다음과 같습니다: 버전 전환, 호환성 깨는 변경 수정, 릴리스 전 테스트. 실제로는 이렇게 진행됩니다.

1. 이전 SDK 메이저 버전을 고정하세요. 예를 들어 Python에서는 anthropic<2, npm에서는 "@anthropic-ai/sdk": "^0"입니다.
2. 코드와 설정에서 temperature, top_p, top_k, X-Api-Key, completions.create, 그리고 위 표의 모든 Admin API 필드를 검색하세요.
3. 샘플링을 결정하세요. Claude 4.7 이상에서는 파라미터를 삭제하세요. 이전 모델에서는 기본 샘플링을 수용하거나 해당 호출을 2023-06-01에 유지하세요.
4. 메시지 구성을 수정하세요. assistant 측 문서를 user 턴으로 옮기고 user 텍스트 블록에서 citations를 제거하세요.
5. 동일한 페이로드를 두 버전에서 테스트하고 상태 코드와 응답 형태를 비교하세요.
6. SDK 업그레이드와 코드 수정을 함께 배포하세요. Anthropic은 수정 사항과 함께 업그레이드를 릴리스하라고 말하며, 그 전에 릴리스하지 말라고 합니다.

SDK 없이 전환하려면 헤더 하나면 됩니다:

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, Claude"}]
  }'

해당 본문에 "temperature": 0.2를 추가하면 400이 반환됩니다. 같은 본문을 anthropic-version: 2023-06-01로 전송하면 성공합니다. 이 두 결과의 쌍이 바로 5단계에서 프로덕션으로 전송하는 모든 페이로드에 대해 잡아내야 하는 것입니다.

Apidog CLI로 Claude Code가 두 버전을 테스트하게 하기

5단계는 수작업으로 하면 지루합니다. 수십 가지 페이로드 형태가 있고, 각각을 두 번씩 실행해야 합니다. 대신 코딩 에이전트에게 맡기세요. Apidog CLI는 Claude Code(또는 Codex, Cursor, OpenCode)에 테스트 케이스를 생성하고 실행하는 명령을 제공하므로, 에이전트가 비교를 수행하고 여러분은 요약을 읽으면 됩니다.

한 번만 설정하세요:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

그런 다음 Claude Code에 프롬프트 하나를 주세요:

In Apidog project <id>, create an environment "claude-api" with base URL
https://api.anthropic.com. For each JSON payload in ./fixtures/claude/, add a
POST /v1/messages test case that sends the header anthropic-version: {{anthropic_version}}
and asserts status 200 and a non-empty content array. Run every case twice, once with
anthropic_version=2023-06-01 and once with 2026-10-21, and list each case that passes
on the old version but fails on the new one, with the error message.

에이전트는 아무것도 작성하기 전에 각 페이로드 스키마를 확인한 다음 케이스를 실행합니다:

apidog environment create claude-api --project <id> --base-url https://api.anthropic.com
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2023-06-01" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "anthropic_version=2026-10-21" -r cli,json

--env-var 플래그는 테스트 케이스를 건드리지 않고 헤더 값을 바꾸므로, 차이는 변수 하나뿐입니다. --upload-report를 추가하면 Apidog 앱에서 두 실행을 모두 볼 수 있고, 2026-10-21 실행을 -r junit과 함께 CI에 넣으면 의존성 범프가 temperature 필드를 프로덕션으로 배포할 수 없게 됩니다. Claude Code에서의 Apidog CLI 가이드에서 설정을 더 자세히 다루며, apidog run 레퍼런스에 모든 플래그가 나열되어 있습니다. Apidog의 무료 플랜은 최대 4명의 사용자를 지원합니다.

2023-06-01은 지원 중단되었나요?

아직 폐기 날짜는 발표되지 않았습니다. 버전 관리 페이지에는 2023-06-01이 지원 중단 공지 없이 나열되어 있으며, 마이그레이션 가이드 자체도 기본값이 아닌 temperature가 필요한 요청은 2023-06-01에 유지하라고 안내합니다. Anthropic은 여전히 "가능하면" 최신 버전을 권장합니다.

이는 계획 수립에 중요합니다. 오늘의 업그레이드는 선택 사항이지만, 2026-10-21은 3년 이상 만에 나온 첫 새 버전이며, 향후 호환성 깨는 변경도 같은 방식으로 도입될 것이므로, 버전 테스트를 지금부터 일상적인 CI 작업으로 취급하는 것이 나중에 급하게 마이그레이션하는 것보다 저렴합니다. 이미 Claude API 속도 제한이나 Claude API 비용을 조정하고 있다면, 같은 파이프라인에 버전 검사를 추가하세요. API 버전 관리 모범 사례 가이드에서 이와 같은 날짜 기반 버전이 왜 더 쉽게 만드는지 설명합니다.

FAQ

지금 Claude API 버전 2026-10-21로 업그레이드해야 하나요?

아니요. 2023-06-01은 여전히 작동하며 발표된 폐기 날짜가 없습니다. 새 헤더를 전송하거나 이를 기본값으로 하는 SDK 메이저 버전을 설치할 때 업그레이드하게 됩니다.

SDK 업그레이드 후 요청이 400을 반환하는 이유는 무엇인가요?

새 SDK 메이저 버전은 2026-10-21을 전송하며, 이 버전은 temperature, top_p, top_k, assistant 측 document 블록, 그리고 user 텍스트 블록의 citations를 거부합니다. 먼저 페이로드에서 이러한 항목을 확인하세요.

일부 요청에 temperature를 유지할 수 있나요?

네, 해당 특정 요청을 2023-06-01에 유지하면 됩니다. 2026-10-21에서는 대체 설정이 없으며, Claude 4.7 이상 모델은 어차피 기본값으로만 샘플링합니다.

2026-10-21은 Amazon Bedrock에서 작동하나요?

Claude 4.7 이상 모델에서만 작동합니다. 이전 Bedrock 모델은 모델을 전환할 때까지 현재 SDK 버전이나 헤더가 필요합니다.

프록시가 여전히 내 API 키를 볼 수 있나요?

X-Api-Key를 읽는다면 볼 수 없습니다. 새 SDK는 키를 Authorization: Bearer로 전송합니다. 프록시를 업데이트하여 Authorization을 읽거나, SDK가 X-Api-Key를 전송하도록 직접 구성하세요.

새 버전이 스트리밍 이벤트를 변경하나요?

Anthropic은 2026-10-21에 대해 스트리밍 형식 변경을 나열하지 않았습니다. 현재 사용하는 스트리밍 형식은 2023-06-01과 함께 도입되었습니다.