Claude API 2026-10-21 마이그레이션: temperature 제거·Bearer 인증

3년 만에 바뀐 API 버전

Claude API는 모든 요청에 anthropic-version 헤더를 받아요. 지금까지 대부분의 코드는 2023-06-01을 보내 왔고, 2026년 10월 21일에 그다음 버전인 2026-10-21이 공개됐어요. 공식 버전 문서는 가능하면 최신 버전을 쓰라고 권하지만, 2023-06-01을 언제 끝낸다는 안내는 아직 없어요.

같은 날 각 언어의 SDK도 새 메이저 버전이 나왔어요. 이 버전들은 기본으로 2026-10-21을 보내요. 그래서 "버전 헤더는 손대지 않았는데 패키지만 올렸더니 400이 난다"는 일이 생길 수 있어요.

C#(13.0.0), PHP(1.0.0), Ruby(2.0.0)도 함께 바뀌었어요. 새 SDK와 CLI의 라이선스는 MIT에서 Apache 2.0으로 바뀌었으니, 의존성 라이선스 목록을 관리한다면 같이 고쳐 두세요.

SDK를 쓰지 않고 HTTP로 직접 부른다면 헤더 값만 바꾸면 돼요.

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-haiku-5-5","max_tokens":512,
       "messages":[{"role":"user","content":"안녕하세요"}]}'

가장 많이 걸릴 변경: 샘플링 파라미터 제거

새 버전에서 temperature, top_p, top_k를 보내면 모든 모델에서 400 오류가 나요. 마이그레이션 가이드는 기본값을 그대로 보내도 오류라고 분명히 적고 있어요. "temperature: 1은 안전하겠지" 하고 남겨 둔 코드도 걸린다는 뜻이에요.

파라미터를 빼면 기본값(temperature 1.0)으로 샘플링해요. Claude 4.7 이후 모델은 원래 기본값만 받았기 때문에 결과가 달라지지 않아요. 반면 Claude Sonnet 4.6처럼 다른 값을 받던 모델에서 temperature를 낮춰 일관성을 얻고 있었다면, 그 효과가 사라지고 대신할 설정도 없어요. 이런 요청은 파라미터를 빼거나, 그 요청만 2023-06-01에 남겨 두라는 것이 공식 안내예요.

먼저 코드에서 세 파라미터를 보내는 곳을 찾아보세요. 배치(Message Batch) 요청과 토큰 계산 요청도 같은 규칙을 따라요.

# 샘플링 파라미터를 보내는 곳 찾기 (snake_case·camelCase 모두)
git grep -nE '\b(temperature|top_p|top_k|topP|topK)\b' -- '*.ts' '*.tsx' '*.py' '*.java' '*.kt'

결정적인 출력이 필요했다면 이제는 샘플링 값 대신 구조로 풀어야 해요. 예를 들어 분류 작업은 출력 형식을 정해진 선택지(enum) 스키마로 묶어 두면, temperature 없이도 답이 흔들릴 여지가 크게 줄어요.

SDK 메이저 업그레이드: Bearer 인증과 프록시

API 버전과 별개로, 새 SDK와 CLI는 키를 보내는 방식이 바뀌었어요. 예전에는 X-Api-Key 헤더에 넣었지만, 이제는 Authorization: Bearer <키>로 보내요. Claude API 자체는 두 헤더를 모두 받아요.

문제는 중간에 끼어 있는 것들이에요. 사내 게이트웨이(gateway, 요청을 대신 받아 넘겨주는 서버)나 프록시가 X-Api-Key를 읽어 사용량을 세거나 키를 바꿔 끼우고 있다면, 업그레이드 직후 인증이 깨질 수 있어요. 로그에서 키를 가리는 필터, 테스트용 가짜 서버(stub)도 같은 이유로 확인 대상이에요.

게이트웨이를 당장 고칠 수 없다면 클라이언트에서 예전 헤더로 보내도록 되돌릴 수 있어요. TypeScript SDK v1 기준이에요.

import Anthropic from "@anthropic-ai/sdk";

// 게이트웨이가 X-Api-Key만 읽을 때: Authorization은 빼고 예전 헤더로 보내기
const client = new Anthropic({
  apiKey,
  defaultHeaders: { "X-Api-Key": apiKey, Authorization: null },
});

몇 가지 동작도 함께 바뀌었어요. 클라이언트 하나는 자격 증명 하나만 보내고, 요청 옵션에 X-Api-Key를 따로 넣으면 키가 바뀌는 대신 두 키가 모두 나가요. ant CLI는 --api-key·--auth-token 플래그가 없어졌어요. 명령줄에 쓴 값이 셸 기록과 프로세스 목록에 남기 때문이에요.

그 밖의 변경: 문서 블록·인용·관리 API 필드

메시지 쪽에는 두 가지가 더 있어요. assistant 메시지에 document 블록을 직접 넣으면 400이 나니 문서는 user 메시지로 보내야 해요. 또 user 메시지의 text 블록에 비어 있지 않은 citations 배열을 넣어도 400이에요. Claude가 이전에 돌려준 인용을 assistant 메시지로 되돌려 보내는 것은 여전히 괜찮아요.

Admin API를 읽는 운영 도구가 있다면 필드 이름을 바꿔야 해요. RBAC 그룹의 roles는 role_ids, 역할의 name은 display_name, 사용량 한도 항목의 group_type은 group.type이 됐어요. API 키 응답의 workspace_id는 사라지고 scope.workspace_id를 써요.

SDK 타입도 정리됐어요. MessageParam이 역할별 타입(UserMessageParam, AssistantMessageParam 등)의 합집합으로 바뀌었고, TypeScript·Go·Java·Ruby SDK와 CLI에서는 오래된 Text Completions API가 빠졌어요. 딕셔너리나 객체 리터럴로 메시지를 만드는 코드는 대부분 그대로 동작해요.

업그레이드 순서 체크리스트

공식 가이드의 순서를 실무 기준으로 풀면 이래요.

1. 의존성 확인: Claude SDK를 직접 쓰는지, 다른 프레임워크가 감싸서 쓰는지 봐요. 래퍼(wrapper)는 자기 버전 헤더를 따로 보내는 경우가 많아요.
2. 샘플링 파라미터 제거: 위의 검색으로 찾은 곳을 지우고, 결과 품질을 평가 세트로 다시 확인해요.
3. 인증 경로 점검: 게이트웨이, 로그 필터, 테스트 스텁이 어느 헤더를 읽는지 확인해요.
4. 한 번에 배포: SDK 업그레이드와 코드 수정을 같은 배포에 묶어요. 가이드도 둘을 함께 내보내라고 해요.
5. Bedrock 확인: Amazon Bedrock에서는 Claude 4.7 이후 모델만 새 버전을 써요. 이전 모델을 부른다면 지금 SDK 버전을 유지하세요.

TypeScript에서 Bedrock·Vertex 같은 플랫폼 패키지를 함께 쓴다면 그것들도 1.0으로 같이 올려야 해요. 하나만 올리면 패키지 관리자가 오래된 SDK 사본을 하나 더 설치해요.

우리 스택에서는: AI SDK와 Haiku 5.5

인텐트코드 홈페이지의 챗봇은 Claude Haiku 5.5를 Vercel AI SDK(ai v4, @ai-sdk/anthropic 1.2)로 부르고 있어요. 설치된 패키지를 직접 열어 보니, 이 래퍼는 anthropic-version: 2023-06-01과 x-api-key를 스스로 붙여 보내요. 그래서 공식 SDK가 메이저 버전을 올렸어도 지금 우리 요청은 바뀌지 않아요.

다만 우리 코드에는 temperature를 1로 명시해 보내는 곳이 세 군데 있어요. Haiku 5.5가 기본값이 아닌 temperature를 400으로 막는데, AI SDK v4는 값을 정하지 않으면 0을 보내기 때문에 넣어 둔 장치예요. 나중에 래퍼가 2026-10-21로 넘어가면 이 줄이 오히려 400의 원인이 돼요. 그래서 래퍼를 올리는 날에는 이 세 줄을 함께 지우는 것을 체크리스트에 적어 뒀어요.

정리하면, 이번 버전은 "기본값만 쓰는 최신 모델" 시대에 맞춰 API를 단순하게 만드는 변화예요. 새 모델을 붙이기 전에 미리 옮겨 두면, 모델 교체와 API 변경이 한 배포에 겹치는 일을 피할 수 있어요.