Claude API 2026-10-21 이관 전 temperature 호출부 찾기
Claude API 버전을 2026-10-21로 올리는 작업을 확인했습니다. 문서를 읽어 보니 SDK 의존성만 바꾸는 PR은 바로 내기 어렵습니다. 새 SDK와 ant CLI가 이 버전을 기본으로 보내는데, 기존 요청 본문에 남아 있던 샘플링 설정이 있으면 서버가 400으로 돌려보냅니다.
문서를 열어 보니 temperature=1.0처럼 기본값을 명시한 요청도 같은 오류가 납니다. 값의 범위 문제가 아니라, 필드 자체가 새 버전에서 받지 않는 항목이었습니다.
먼저 결론부터
- API 버전
2026-10-21은 breaking change를 포함하며, 새 SDK와antCLI는 이 버전을 기본으로 사용합니다. - Messages API 요청에
temperature,top_p,top_k중 하나라도 남아 있으면400오류가 납니다. 기본값을 넣은 경우도 같습니다.
{
"temperature": 1.0,
"top_p": 1,
"top_k": 1
}- 세 필드를 빼면 서버 기본값으로 샘플링하며, temperature 기본값은
1.0입니다. - 온도를 낮춰 출력 일관성을 얻던 호출은 새 버전에서 같은 동작을 유지할 대체 설정이 없습니다.
- SDK 업그레이드와 코드 수정은 같은 배포에 묶어야 합니다. 의존성만 먼저 올리면 기존 호출이 바로 깨질 수 있습니다.
- 이 저장소의
~/blog-automation/scripts에서는anthropic과temperature검색 결과가 모두0건이었습니다. 이 저장소 스크립트에는 이번 이관 대상이 없었습니다.
먼저 호출부가 있는지 찾았습니다
문서를 읽은 뒤 이 저장소에서 바로 바꿀 파일이 있는지부터 확인했습니다. ~/blog-automation/scripts 아래의 파이썬 소스를 대상으로 anthropic과 temperature 문자열을 검색했습니다.
grep -nE 'anthropic|temperature' ~/blog-automation/scripts/*.py결과는 없었습니다. 이 저장소의 스크립트는 Anthropic SDK를 직접 부르지 않았고 temperature를 넘기는 코드도 없었으니, 여기까지 확인한 범위에서는 API 버전이나 SDK 버전을 올릴 작업 자체가 없었습니다.
다만 검색 범위는 이 저장소 스크립트뿐이었습니다. 다른 프로젝트, 별도 배포 환경, Claude Code 설정은 확인하지 않았으므로 검색 결과가 없었다는 말이 컴퓨터 전체에 호출부가 없다는 뜻은 아니었습니다.
이관을 실제 요청으로 수행하거나 400 오류를 재현한 것도 아닙니다. 이번 기록은 문서를 읽고 현재 저장소가 해당되는지 판단하는 데서 멈춘 확인 과정입니다.
temperature는 값이 아니라 필드가 문제였습니다
2023-06-01에서 2026-10-21로 옮기는 가이드에서는 Messages API의 샘플링 필드 세 가지를 제거하라고 적고 있습니다.
temperature
top_p
top_k값을 비워 보내는 문제가 아닙니다. 필드를 포함하는 순간 400이 됩니다. 기존 코드에서 습관처럼 temperature=1.0을 넣어 두었다면, 결과가 기본값과 같다는 이유로 통과하지 않습니다.
Claude 4.7 이후 모델은 원래 기본값만 받아 동작했으므로, 이 모델만 쓰는 호출은 필드를 빼도 동작이 달라지지 않습니다. 반대로 Claude Sonnet 4.6처럼 다른 temperature 값을 받을 수 있던 모델에서 낮은 값을 사용했다면 상황이 달라집니다.
그 효과는 사라집니다.
문서에는 대체 설정이 없다고 적혀 있습니다. 낮은 temperature에 기대던 요청은 매개변수를 제거하거나, 해당 요청만 기존 2023-06-01 버전에 남겨야 합니다. 같은 코드 경로에서 모델만 바꾸는 구조라면 모델 이름보다 요청 본문의 필드 유무를 먼저 보게 됩니다.
메시지 블록도 함께 걸러집니다
샘플링 설정만 제거하면 끝나는 이관은 아니었습니다. document 블록을 assistant 메시지에 직접 넣으면 새 버전에서는 400 오류가 납니다. 이 블록은 user 메시지로 보내야 합니다.
인용 처리도 같은 방식으로 확인해야 합니다. user 메시지 안의 text 블록에 비어 있지 않은 citations 배열을 넣으면 오류가 납니다.
반면 assistant 메시지의 citations와 아래 설정은 계속 허용됩니다.
{
"citations": {
"enabled": true
}
}이 차이 때문에 메시지 배열을 공통 변환 함수에서 조립하는 코드는 조금 더 살펴볼 필요가 있습니다. 단순한 텍스트 요청만 쓰던 곳에서는 드러나지 않다가, 문서 첨부나 인용 응답을 붙인 경로에서만 실패할 수 있기 때문입니다.
SDK와 프록시의 인증 경로도 바뀝니다
새 릴리스는 Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0, ant CLI 2.0.0을 함께 냈습니다. 라이선스도 MIT에서 Apache 2.0으로 바뀌었습니다.
SDK와 CLI는 API 키를 X-Api-Key 대신 아래 형식으로 보냅니다.
Authorization: Bearer <key>API를 직접 호출하는 프로그램은 두 헤더를 모두 받을 수 있으므로, 호출 코드만 놓고 보면 반드시 바꿀 부분은 없습니다. 그런데 중간 프록시나 게이트웨이가 X-Api-Key만 읽어 키를 꺼내는 구조라면 이야기가 달라지는데, SDK를 올린 뒤 요청은 나가도 프록시 쪽 인증 정보가 비는 경로가 생기기 때문입니다.
이 부분은 코드 검색만으로 끝나지 않습니다. 요청 헤더를 바꾸는 프록시 설정, 인증 로그, 게이트웨이 규칙을 함께 봐야 합니다. SDK 변경이 애플리케이션 내부 호출 형식만 바꾸는 일이 아니었던 이유입니다.
SDK 없이 HTTP 요청을 보낸다면 버전 헤더를 직접 바꿉니다.
anthropic-version: 2026-10-21Go SDK는 모듈 경로도 바뀝니다.
github.com/anthropics/anthropic-sdk-go/v2기존 import를 그대로 둔 채 버전만 올리는 방식은 맞지 않습니다.
오래된 모델과 Admin API는 분리해서 봅니다
Amazon Bedrock에서는 2026-10-21이 Claude 4.7 이후 모델에만 열립니다. 더 오래된 모델을 쓰는 호출은 사용하던 SDK 버전이나 헤더 값을 유지해야 합니다. 같은 서비스 안에서 Bedrock 호출과 직접 API 호출이 섞여 있다면, 버전 값을 일괄 치환하는 작업도 피해야 합니다.
Admin API를 쓰는 코드도 별도 검색 대상입니다. API 키 목록의 workspace_id는 사라지고 scope를 읽어야 합니다. 전체 워크스페이스 키는 아래 형태로 표현됩니다.
{
"scope": {
"type": "organization"
}
}기존에 workspace_id가 null이면 Default Workspace로 처리하던 코드가 있었다면 새 응답에서는 그 분기가 성립하지 않습니다. 요청을 보내는 코드뿐 아니라 응답을 읽는 관리 기능도 이관 범위에 들어갑니다.
이번 저장소에서는 호출부가 0건이라 수정으로 이어지지 않았습니다. 그래도 SDK 버전만 올리는 변경이 들어오면, 먼저 샘플링 필드와 메시지 블록을 찾고 그다음 프록시의 인증 헤더를 확인하는 순서로 보게 됩니다. 문서가 말한 “업그레이드와 수정의 동시 배포”는 이 순서를 거친 뒤에야 가능해집니다.