claude-sonnet-5-5 전환 가이드 — 단가는 그대로, 파괴적 변경 5가지

AI트렌드 API 마이그레이션 Anthropic Claude Sonnet 5.5 LLM API claude-sonnet-5-5

AI 트렌드·이슈

목록 보기

116/118

안녕하세요, 미니지식공간입니다.

claude-sonnet-5-5가 2026년 9월 28일 공개됐다. Claude Sonnet 5.5 가격은 $2/$10로 Sonnet 5와 동일하지만, 모델 문자열만 바꿔 끼우면 끝나는 업데이트는 아니다. 공식 문서가 파괴적 변경(breaking change) 다섯 가지를 명시해 두었기 때문이다.

TL;DR

단가 동결: 입력 $2 / 출력 $10 / 캐시 읽기 $0.20 — Sonnet 5와 한 항목도 다르지 않다.

코드는 수정 필요: thinking: disabled 폐지, tool_choice: any|tool 400 오류, computer 툴 버전 교체.

노력 수준(effort)이 재보정됐으므로 Sonnet 5 설정값을 그대로 이식하면 안 된다.

1. 바뀐 것과 바뀌지 않은 것

바뀌지 않은 쪽부터 보면 간단하다. 공식 가격 문서 기준 claude-sonnet-5-5는 입력 100만 토큰당 $2, 출력 $10, 캐시 읽기 $0.20, 5분 캐시 쓰기 $2.50, 1시간 캐시 쓰기 $4다. Sonnet 5와 전 항목 동일하다. 상위 모델인 claude-opus-5-5는 $4/$20이므로 정확히 두 배다.

바뀐 쪽은 전부 API 표면이다. Anthropic이 발표한 "과제당 비용 최대 30% 절감"은 단가 인하가 아니라 토큰과 툴 호출이 줄어든 결과라는 설명이고, 그 대가로 요청 스키마 몇 군데가 호환되지 않게 됐다.

2. 파괴적 변경 5가지

공식 문서 What's new in Claude Sonnet 5.5가 나열한 항목을 그대로 정리한다.

#	변경	조치
1	`thinking: {"type": "disabled"}` 미지원	`{"type": "between_tools"}` 로 교체 (effort high 이하)
2	`tool_choice` 의 `any` / `tool` 강제 미지원	`auto` + strict tool use 로 전환. 기존 값은 400 응답
3	thinking 블록이 모델·대화에 묶임	서로 다른 모델 간 thinking 블록 재사용 불가. 대화는 append-only 유지
4	`computer_20251124` 지원 종료	Claude API·Google Cloud에서 `computer_toolset_20260801` 사용
5	advisor 조합 제한	Opus 4.8 / 4.7 / Sonnet 5 advisor + Sonnet 5.5 executor 조합 불가

출처: https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5

3번은 특히 놓치기 쉽다. 여러 모델을 라우팅으로 섞어 쓰는 구조라면, 앞 단계 모델이 남긴 thinking 블록을 뒤 단계 모델에 그대로 넘기던 경로를 먼저 끊어야 한다.

3. 최소 호출

공식 모델 개요 문서의 Messages API 예제에서 모델 문자열만 claude-sonnet-5-5로 둔 형태다.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

출처: https://platform.claude.com/docs/en/about-claude/models/overview

4. 문서에 명시된 파라미터 값

공식 문서에 기재된 파라미터와 허용값만 옮긴 스니펫이다. 문서에 없는 조합은 넣지 않았다.

model                : claude-sonnet-5-5
context window       : 1M tokens (input) / 128K tokens (max output)

output_config.effort : low | medium | high | xhigh | max
                       Claude API 기본값 high
                       Claude Code / 앱 기본값 medium

thinking.type        : between_tools      # Sonnet 5 의 "disabled" 를 대체
tool_choice.type     : auto               # "any", "tool" 은 400
computer tool        : computer_toolset_20260801   # computer_20251124 대체

배포처               : Claude API / AWS Bedrock / Google Cloud / Microsoft Foundry

출처: https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5, https://platform.claude.com/docs/en/about-claude/models/overview

노력 수준에 대해 문서가 붙인 권고는 이렇다. 일반 용도는 high에서 시작, 에이전트형 코딩과 다단계 툴 사용은 명세가 분명하면 medium·어려우면 high, 대화나 지연에 민감한 경로는 medium이나 low. 그리고 "노력 수준이 재보정됐으니 Sonnet 5 설정을 이월하지 말고 스윕을 다시 돌리라"는 문장이 명시돼 있다.

5. 성능 수치

전부 Anthropic 자사 발표 수치이며 독립 검증 결과가 아니다.

벤치마크	Sonnet 5.5	Opus 5.5	Sonnet 5
Terminal-Bench 4.0	70.6%	66.4%	10.3%
CursorBench 4.0	55.5%	57.8%	-
GDPval-AA v2.1	1844	1846	1449
OSWorld 2.1	80.1%	81.8%	57%
Chartography	61.6%	64.4%	15.6%

FrontierCode 1.1은 Xhigh 노력 수준에서 52.1%로 발표됐다. 속도 쪽은 "Sonnet 5 대비 출력 생성 30% 이상 빠름", 비용 쪽은 "과제당 최대 30% 절감"이 자사 주장이다. 절감의 출처가 단가가 아니라 토큰·툴 호출 수라는 점은 문서와 보도 양쪽에서 동일하게 설명된다.

6. 전환 전 체크리스트

thinking: {"type": "disabled"} 를 쓰는 코드 경로 전수 검색 → between_tools 로 교체.
tool_choice 에 any 또는 특정 툴 이름을 강제하는 호출 전수 검색 → auto + strict tool use.
컴퓨터 사용 툴 정의를 computer_toolset_20260801 로 교체(Claude API·Google Cloud 한정 변경).
모델 라우팅 구조라면 모델 간 thinking 블록 전달 경로 제거.
effort 값은 기본값(Claude API high)부터 다시 측정. 이월 금지.
과제 20~50건을 Sonnet 5와 Sonnet 5.5로 각각 돌려 과제당 총 토큰·툴 호출 수 비교. 단가가 같으므로 이 수치가 곧 절감분이다.

자주 묻는 질문

Q. claude-sonnet-5-5로 바꾸면 요금이 오르나?
아니다. 공식 가격 문서 기준 입력 $2 / 출력 $10 / 캐시 읽기 $0.20으로 Sonnet 5와 동일하다. 총비용 변화는 단가가 아니라 토큰·툴 호출 수에서만 발생한다.

Q. 기존 API 코드 수정이 필요한가?
필요하다. 최소한 thinking 과 tool_choice 두 곳은 손봐야 하고, 컴퓨터 사용 툴을 쓰면 툴 버전도 교체해야 한다. 그대로 두면 tool_choice 쪽은 400 오류로 즉시 실패한다.

Q. Sonnet 5의 effort 설정을 그대로 써도 되나?
공식 문서가 재보정을 명시하며 이월하지 말라고 안내한다. 같은 값이 같은 품질·비용을 뜻하지 않으므로 전환 시 다시 측정하는 편이 맞다.

마무리

요약하면 이번 릴리스는 "요금표는 안 건드리고 API 표면을 건드린" 업데이트다. 전환 비용은 대부분 2절의 다섯 항목에서 나오고, 회수는 6절의 마지막 측정에서 확인된다. 같은 계열 상위 모델의 단가 구조는 GPT-6 Sol·Luna vs Claude Opus 5.5 API 단가 비교 글에 정리해 두었다.