Claude 앱에서 모델을 고르는 일과, 프로그램이 API로 호출하는 모델을 바꾸는 일은 다릅니다. API는 프로그램이 모델에 요청을 보내고 답을 받는 연결 방식입니다. Sonnet 5.5로 바꿀 때는 모델 이름뿐 아니라 요청 설정과 답변을 읽는 코드도 확인해야 합니다. 이 글은 어떤 작업에 Sonnet을 쓰면 좋은지 먼저 설명하고 API를 쓰는 개발자가 옮길 때 확인할 변경점을 이어서 살펴봅니다.

한눈에 보기

  • Sonnet 5.5는 Opus 5.5 다음으로 나온 Claude 5.5 계열의 두 번째 모델입니다. Sonnet 5보다 30% 빠르고 대부분의 작업에서 비용이 최대 30% 줄어든다고 합니다.
  • 토큰 단가는 Sonnet 5와 같습니다. 청구액이 달라지는 이유는 같은 일에 쓰는 토큰이 줄기 때문입니다.
  • 범위가 분명한 일상 작업은 Sonnet 5.5, 오래 이어지는 판단이 필요한 일은 Opus 5.5가 기본 선택입니다.
  • API로 Sonnet 5에서 옮긴다면 추론 방식인 thinking 설정과 도구 호출 설정을 점검해야 합니다. 화면을 조작하는 computer use와 다른 모델에 조언을 구하는 advisor를 쓰는 경우도 변경점이 있습니다.

원문 소개

Addy Osmani가 2026년 9월 28일 claude.dev 블로그에 올린 Playbooks 글입니다. API로 모델을 붙여 쓰는 개발자를 위한 실무 안내서입니다. 에이전트나 코딩 도구를 운영하면서 모델 선택과 비용을 고민하는 분께 맞습니다.

언제 Sonnet이고 언제 Opus인가

원문의 기본 기준은 할 일이 구체적으로 정해져 있고 결과를 확인할 수 있는가입니다. 이런 작업에는 Sonnet 5.5를 권합니다. 버그 수정, 기능 추가, 문서와 슬라이드와 스프레드시트 작성, 조사와 리뷰가 여기에 들어갑니다. 명세란 무엇을 만들고 어떤 조건을 만족해야 하는지 정리한 요구사항입니다.

반대로 여러 단계를 오래 이어 가며 판단해야 하는 코딩이나 어려운 지식 업무에는 Opus 5.5를 권합니다. 에이전트형 코딩은 AI가 파일을 읽고 수정하고 테스트하는 과정을 이어 가는 작업을 말합니다. 원문 발행 시점에는 대량 처리용 Haiku 5.5가 몇 주 안에 나올 예정이라고 소개됐습니다.

원문 사진과 Sonnet 5, Sonnet 5.5, Opus 5.5가 작성한 Python 코드로 그린 결과를 비교

그림 1. 왼쪽부터 원본 사진, Sonnet 5, Sonnet 5.5, Opus 5.5의 결과입니다. 이미지 생성 모델이 아니라 각 모델이 작성한 Python 코드로 그렸습니다. Lance Martin의 데모이며, 전체 성능을 대표하는 시험은 아닙니다. 출처: 원문 .

원문의 데모는 @jkeatn의 코드 페인팅 작업 에서 영감을 얻었고, 원본 사진은 @IceSolst 가 제공했습니다.

요구사항과 확인 방법을 먼저 살펴보세요. 단순히 작업 이름만으로 모델이 정해지지는 않습니다.

토큰은 모델이 읽고 생성하는 텍스트를 세는 단위입니다. 입력은 모델에 보내는 내용, 출력은 모델이 생성한 내용입니다. 원문의 100만 토큰 기준 가격은 Sonnet 5.5가 입력 $2, 출력 $10이고 Opus 5.5는 입력 $4, 출력 $20입니다. 이미 보낸 동일한 입력을 재사용하는 캐시 읽기는 둘 다 $0.20입니다.

100만 토큰당 가격Sonnet 5.5Opus 5.5
입력$2$4
출력$10$20
캐시 쓰기 · 5분$2.50$5
캐시 쓰기 · 1시간$4$8
캐시 읽기$0.20$0.20

입력, 출력, 캐시에 처음 저장하는 쓰기 가격은 Opus 5.5가 Sonnet 5.5의 두 배이고 읽기 가격만 같습니다. 여러 요청을 묶어 처리하는 배치 처리와 동일 입력을 재사용하는 프롬프트 캐싱까지 포함해, Sonnet 5.5의 가격은 Sonnet 5와 같습니다.

단가표만 비교하면 Sonnet 5와 5.5의 차이가 보이지 않습니다. 비용이 줄어드는 이유는 같은 일을 하는 데 드는 토큰 수가 줄기 때문이므로, 실제 비용은 대표 작업을 돌려 봐야 알 수 있습니다.

이미지도 입력 토큰을 씁니다. Sonnet 5.5는 긴 변 2576픽셀까지 받는 고해상도 방식이라, 2000×1500 이미지는 Sonnet 4.6 대비 토큰을 약 2.5배 씁니다. 작은 글자나 세부를 읽어야 하는 작업이 아니라면 보내기 전에 이미지 크기를 줄이는 편이 좋습니다.

한 번에 참고할 수 있는 대화와 자료인 컨텍스트는 1M 토큰이고 한 번에 생성할 수 있는 최대 출력은 128k입니다. M은 백만, k는 천 단위입니다. 큰 컨텍스트를 쓰기 위해 시험 기능용 표시인 베타 헤더를 따로 보낼 필요는 없습니다. API에 지정하는 모델 ID는 claude-sonnet-5-5 입니다.

작업에 쓸 계산 자원의 수준을 알려 주는 effort의 기본값은 Claude API에서 high, Claude Code에서 medium입니다. 같은 모델이라도 쓰는 환경에 따라 기본 설정이 다릅니다.

API로 Sonnet 5에서 옮길 때 확인할 변경점

이 절은 API를 호출하는 코드를 고칠 때 필요한 내용입니다. 400 오류는 보낸 요청의 설정이나 형식을 API가 받아들이지 못했다는 뜻입니다. 모델이 답을 못 찾은 상황과는 다릅니다.

먼저 thinking, 즉 답을 만들기 위한 추론 방식이 바뀝니다. Sonnet 5.5는 기본으로 thinking을 켠 채 동작합니다. 예전처럼 thinking: {"type": "disabled"} 를 보내면 400 오류가 납니다.

시작 단계의 thinking을 끄고 도구 호출 사이에서만 추론하게 하려면 between_tools 를 씁니다. 다만 effort가 low, medium, high일 때만 쓸 수 있고, xhigh나 max와 함께 보내면 400 오류입니다.

답변을 읽는 코드도 확인해야 합니다. API 응답은 텍스트나 thinking 등 서로 다른 종류의 블록을 담습니다. 첫 블록이 thinking일 수 있으므로 content[0].text 로 첫 블록만 읽던 코드는 블록 타입을 보고 텍스트를 읽도록 고쳐야 합니다.

Sonnet 5.5에서 disabled는 오류이고 between_tools는 xhigh나 max와 조합하면 오류입니다. 그 수준을 써야 한다면 모델이 추론량을 조절하는 adaptive thinking을 씁니다.

다른 변경점도 사용하는 기능별로 나눠 보면 됩니다.

  • 도구 호출: tool_choice는 모델이 도구를 고르는 방식입니다. any나 tool로 호출을 강제하면 400 오류가 납니다. 원문은 auto로 보내고, 도구 입력이 정해진 형식을 따르게 하는 strict: true 를 붙이라고 안내합니다.
  • 화면 조작: computer use는 화면을 보고 클릭하거나 입력하는 기능입니다. Claude API와 Google Cloud에서는 computer_toolset_20260801 로만 쓸 수 있고, 예전 computer_20251124 를 선언하면 400 오류입니다. 원문 시점에 Amazon Bedrock은 예전 것도 받습니다.
  • 다른 모델에 조언 요청: advisor는 작업 중 다른 모델에 조언을 구하는 도구입니다. Sonnet 5.5가 실행자일 때 Opus 4.8, Opus 4.7, Sonnet 5는 조언자로 쓸 수 없습니다. 사용할 수 있는 모델에는 Opus 5.5, Opus 5, Sonnet 5.5 자신이 포함됩니다.
  • 진행 메모 표시: 도구 호출 사이의 메모가 한두 문장보다 길면 progress-update thinking 블록으로 옵니다. 기본 display에서는 이 블록이 비어 있습니다. adaptive thinking을 쓴다면 thinking.display 를 설정해야 화면에 메모가 남습니다. between_tools 는 설정 없이도 텍스트가 옵니다. 요청이 성공해도 화면에 메모가 안 보일 수 있어 따로 확인할 항목입니다.

Claude Code에서 /claude-api migrate this project to claude-sonnet-5-5 를 실행하면 모델 ID 교체와 파라미터 수정을 대신 해 줍니다.

옮긴 뒤 튜닝

effort 단계도 다시 조정됐습니다. 같은 이름의 단계라도 Sonnet 5 때와 thinking 토큰 사용량이 다르므로, 이전 설정이 같은 비용과 동작을 낼 것으로 기대하면 안 됩니다.

원문은 요구사항이 분명한 에이전트형 코딩을 medium에서 시작하고 더 어렵거나 긴 작업만 high로 올리라고 권합니다. xhigh와 max는 같은 과제로 평가해서 품질 향상이 확인될 때 씁니다. 추론이 길어져 속도와 비용이 부담된다면 Opus 5.5와 직접 비교해 볼 만합니다.

이전 모델을 보완하려고 넣은 지시도 다시 살펴봅니다. Sonnet 5 때의 거절 관련 조정 문구, 도구 호출 재시도용 보정 코드, “게으르게 작성하지 마라"류의 문구를 지우고 평가부터 다시 돌리라는 조언입니다. 새 모델에서도 필요한 보정인지 확인하는 과정입니다.

캐시를 사용할 수 있는 최소 입력 길이는 512 토큰(Sonnet 5는 1,024)으로 내려갔습니다. 다만 최상위 effort 설정을 요청 사이에 바꾸면 캐시가 무효가 됩니다. Claude Code에서는 v2.1.284부터 Claude API를 사용할 때 sonnet 별칭이 Sonnet 5.5를 가리킵니다. 기본 모델은 Opus 5.5 그대로입니다.

인사이트

아래는 원문에 없는 글쓴이의 해석입니다.

  1. 토큰 단가가 같아도 작업 하나에 드는 비용은 달라질 수 있습니다. Sonnet 5와 Sonnet 5.5의 단가표가 같으므로 실제로 토큰을 얼마나 쓰는지 비교해야 교체의 이점을 판단할 수 있습니다. 평소 자주 하는 작업 몇 건을 두 모델에 맡겨 결과와 사용량을 함께 확인하는 편이 좋겠습니다.

  2. 모델을 바꿀 때는 이름뿐 아니라 요청을 보내고 답변을 읽는 코드도 살펴봐야 합니다. 새 모델이 받지 않는 설정을 보내면 400 오류가 나고 응답에서 텍스트가 아닌 블록을 읽으면 답변을 제대로 표시하지 못할 수 있습니다. 모델 설정을 한곳에 모으고 응답 블록의 종류에 맞춰 읽도록 정리해 두면 다음 교체 때도 확인하기 쉬울 것으로 보입니다. 모델에 주는 지침과 도구, 실행 코드를 묶어 하네스라고 부릅니다.

  3. 데이터 에이전트도 작업별로 요구사항과 확인 방법이 얼마나 분명한지 살펴볼 만합니다. 데이터베이스 조회문인 SQL의 실행처럼 결과를 도구로 확인할 수 있는 단계에는 Sonnet을, 결과의 의미를 해석하고 판단해야 하는 단계에는 Opus를 쓰는 구성을 검토할 수 있습니다. 실제로 잘 맞는지는 같은 작업을 맡겨 비교해야 합니다.

바로 해볼 것

  • API 호출 코드에서 thinking: {"type": "disabled"}, 도구 호출을 강제하는 tool_choice, 첫 응답 블록만 읽는 content[0].text를 검색합니다. 사용하는 곳을 목록으로 만들고, 앞의 변경점 설명과 대조해 고칠 부분을 정합니다.
  • 자주 하는 작업 몇 건을 같은 요청으로 Sonnet 5와 Sonnet 5.5에 맡깁니다. 결과가 요구사항을 충족했는지 확인하고 토큰 사용량과 걸린 시간도 함께 기록합니다.
  • 이전 모델의 부족한 동작을 보완하려고 넣은 프롬프트 문구를 찾아봅니다. 해당 문구를 뺀 버전을 같은 평가 문제로 시험해 새 모델에서도 필요한 지시인지 확인합니다.

원문: Building with Claude Sonnet 5.5