[기획: AI 트렌드] 릴리스 노트엔 한 줄, 문서엔 400 오류 — SDK 메이저를 올리는 순간 Claude API 버전이 2026-10-21로 바뀐다

10월 21일, 릴리스 노트의 한 줄

10월 21일, Anthropic은 Claude API의 새 버전 2026-10-21을 냈습니다. API는 다른 프로그램이 Claude에 요청을 보내고 답을 받아 가는 정해진 통로입니다.

요청에는 anthropic-version이라는 헤더가 붙습니다. 헤더는 요청 내용 앞에 함께 보내는 설정 줄이고, 여기에 적는 날짜가 API 버전입니다. 날짜에 따라 같은 요청에 적용되는 규칙이 달라집니다. 이번 버전은 세 번째이고, 직전의 옛 버전은 2023-06-01입니다.

같은 날 Anthropic은 SDK 일곱 종과, 명령어를 입력해 쓰는 도구인 ant CLI의 새 메이저 버전도 냈습니다. SDK는 Python 같은 프로그래밍 언어마다 API 호출 코드를 미리 짜서 묶어 둔 라이브러리입니다. 메이저 버전은 버전 번호의 맨 앞 숫자이고, 이 숫자가 오르면 예전 코드가 그대로 돌지 않을 수 있습니다. 새 메이저는 모두 새 API 버전을 기본으로 보냅니다.

Python SDK 릴리스 노트에서 이 변화는 한 줄입니다. 예전 코드가 깨질 수 있는 변경을 뜻하는 「BREAKING CHANGES」 제목 아래, 새 API 버전을 지원한다는 문장뿐입니다. 무엇이 깨지는지는 옛 버전에서 옮기는 방법을 적은 마이그레이션 문서에 있습니다.

temperature를 보내면 400 오류

AI 모델의 답은 토큰, 즉 글을 잘게 자른 조각을 하나씩 뽑아 이어 붙여 만들어집니다. 토큰마다 후보 여럿에 그럴듯한 정도가 매겨지고, 그중 하나를 고르는 과정을 샘플링이라고 합니다.

temperature는 이 고르기를 얼마나 흔들지 정하는 다이얼입니다. 낮추면 가장 그럴듯한 후보로 쏠려 같은 질문에 답이 덜 흔들리고, 높이면 덜 그럴듯한 후보도 가끔 뽑힙니다. top_p와 top_k는 고르기 전에 후보 명단을 줄이는 값입니다.

새 버전에서는 이 세 값 가운데 하나라도 요청에 실으면 400 오류가 납니다. 요청 형식이 잘못돼 처리되지 않았다는 뜻의 오류 번호입니다. 기본값을 그대로 적어 보내도, 어느 모델을 부르든 마찬가지입니다.

세 값을 지우면 요청은 temperature 1.0을 포함한 기본값으로 샘플링됩니다. Claude 4.7 이후의 새 모델은 원래 기본값만 허용되던 모델이라, 문서 표현대로 전과 같이 샘플링됩니다.

5월 28일 릴리스 노트에는 이미 Opus 4.8에 기본값이 아닌 값을 보내면 Opus 4.7과 마찬가지로 400 오류가 난다고 적혀 있습니다. 새 모델에서는 Anthropic이 이미 걸어 둔 제한을 기본값까지 넓혀 API 버전의 규칙으로 옮겨 적은 셈입니다(우리 판단). 앞선 글에서 우리는 Anthropic 이용정책 개정을 집행이 먼저고 문서가 나중인 순서로 읽었는데Anthropic 이용정책 개정, 이미 하던 집행을 적은 절들 사이에 새로 들어간 하드웨어 요건, 이번에는 문서가 늦은 이유가 아래의 버전 약속에 있었습니다(우리 판단).

새 모델에서 temperature를 낮출 수 없게 된 시점은 이번 버전이 아니라 그 전입니다. 이번 버전으로 샘플링이 실제로 달라지는 요청은 Sonnet 4.6처럼 다른 값이 허용되던 모델에 기본값이 아닌 값을 보내던 요청입니다. temperature를 낮춰 답을 고르게 받던 요청은 그 효과를 잃습니다. 문서에는 「No other setting replaces it」, 즉 대신할 설정이 없다고 적혀 있습니다. 문서에 적힌 선택지는 값을 빼거나, 그 요청만 옛 버전에 남겨 두는 것입니다.

왜 새 버전이어야 했나

Anthropic의 버전 문서에는 한 버전 안에서 지키는 약속이 적혀 있습니다. 이미 있는 입력·출력 파라미터는 그대로 둔다는 것입니다. 파라미터는 요청과 응답에 담기는 항목 하나하나입니다. 반면 선택 입력을 더하거나 특정 오류가 나는 조건을 바꾸는 일은 같은 버전 안에서도 허용됩니다.

temperature를 아예 받지 않게 하려면 이미 있는 입력을 빼야 하니, 이 약속 안에서는 새 날짜를 붙일 수밖에 없었습니다(우리 판단). 새 모델에서 기본값이 아닌 값에 오류를 낸 제한은 오류 조건의 변경이라, 같은 버전 안에서도 가능했다고 우리는 봅니다. 값의 범위를 좁히는 일은 옛 버전에서, 입력을 없애는 일은 새 버전에서 일어났습니다(우리 추론). 버전 날짜를 고정해 두면 지켜지는 것은 항목의 이름이지, 그 항목에 넣을 수 있는 값이 아니었던 셈입니다(우리 판단). 옛 버전 이후 3년 4개월 남짓 만입니다(버전 이름의 날짜로 센 우리 계산).

헤더를 직접 고치지 않아도 바뀌는 API 버전

SDK를 쓰는 프로그램의 요청에는 그 SDK의 메이저 버전이 나온 때의 API 버전이 실립니다. 이전 SDK와 CLI는 모든 요청에 옛 버전의 날짜를 실어 보냈습니다. 그래서 개발자가 헤더를 한 줄도 고치지 않아도, SDK를 새 메이저로 올리면 요청의 날짜가 바뀝니다.

SDK 없이 부른다면 개발자가 버전 헤더의 날짜를 직접 바꿔 적어야 새 버전으로 넘어갑니다. 새 SDK의 타입, 즉 코드에 넣을 수 있는 값을 미리 정해 둔 정의에서도 샘플링 값 세 개가 빠졌습니다. Anthropic의 코딩 도구 Claude Code에는 코드를 새 버전으로 옮기는 명령이 추가됐습니다.

새 메이저에는 API 버전과 상관없는 변경도 함께 들어 있습니다. 사용 조건을 정한 라이선스가 MIT에서 Apache 라이선스로 바뀌었습니다. TypeScript·Go·Java·Ruby SDK와 CLI에서는 옛 호출 방식인 Text Completions API가 빠졌습니다. API 버전 쪽에도 샘플링 값 말고 바뀐 규칙이 있습니다. 모델 차례의 메시지에 문서 첨부를 직접 넣거나, 사용자 메시지의 텍스트에 인용 목록을 채워 보내도 400 오류가 납니다. 관리용 Admin API 등의 응답에서는 이름이 바뀐 항목의 옛 이름이 빠집니다.

Amazon Bedrock은 예외입니다. 아마존 클라우드에서 Claude를 쓰는 이 서비스에서는 새 버전을 Claude 4.7 이후 모델에만 쓸 수 있습니다. 그보다 옛 모델을 부른다면 지금 쓰는 SDK 버전에 머물라고 문서에 적혀 있습니다.

고칠 곳은 호출 코드와 API 사이에 있다

새 SDK와 CLI는 API 키를 다른 헤더에 실어 보냅니다. API 키는 요청을 보낸 계정을 확인하는 비밀 문자열입니다. 예전 X-Api-Key 헤더 대신 Authorization: Bearer <키> 형식을 씁니다(Python SDK의 AnthropicFoundry는 예외).

Claude API는 두 헤더를 모두 받으므로, API를 직접 부르는 프로그램은 바꿀 것이 없습니다. 고칠 곳은 프로그램과 API 사이에서 요청을 받아 넘기는 프록시나 게이트웨이 같은 중간 장치입니다. 이런 장치가 X-Api-Key를 읽거나 붙이도록 짜여 있다면 Authorization으로 바꾸라고 문서에 적혀 있습니다.

우리가 확인한 문서로는 옛 버전을 언제까지 쓸 수 있는지 알 수 없습니다. 우리가 전문을 대조한 마이그레이션 문서에는 옛 버전에 남는 길이 적혀 있고, 종료 일정은 없습니다. 그 일정이 나오는지가 앞으로 볼 일입니다.

문서대로라면 요청에 temperature를 실을 수 없게 됐어도 새 모델의 샘플링은 그대로입니다. SDK 메이저를 올리면 요청 내용의 규칙과 함께 요청에 실리는 날짜와 키 헤더도 바뀝니다. 호출 코드에 남은 샘플링 값은 새 SDK의 타입이 먼저 드러냅니다. SDK가 드러내지 못하는 곳은 그 바깥, 키 헤더를 읽는 중간 장치와 Bedrock에서 옛 모델을 부르는 요청입니다. 그래서 이번에 먼저 살필 곳은 코드 한가운데보다 코드와 API 사이입니다(우리 판단).