Claude Sonnet 5.5 API를 사용하려면, `https://api.anthropic.com/v1/messages`로 POST 요청을 보내십시오. 이때 `"model": "claude-sonnet-5-5"`, `x-api-key` 헤더에 API 키, 그리고 `anthropic-version: 2023-06-01`을 포함해야 합니다. 이 API는 입력 토큰 백만 개당 $2, 출력 토큰 백만 개당 $10의 비용이 들며, 최대 1백만 토큰의 컨텍스트를 읽고 최대 12만 8천 토큰을 작성할 수 있습니다. 기본적으로 적응형 사고(adaptive thinking)를 실행하며, 기본 노력(effort) 수준은 `high`입니다.
Anthropic은 2026년 9월 28일에 Sonnet 5.5를 출시했습니다 (Claude Sonnet 5.5란 무엇인가에서 사양 및 벤치마크를 다룹니다). 이 가이드는 curl, Python, TypeScript에서의 첫 호출, 그리고 노력(effort), 사고(thinking), 도구(tools), 스트리밍(streaming), 거부(refusals), 속도 제한(rate limits)에 대해 설명합니다. Sonnet 5 코드를 이전하시나요? Sonnet 5.5 vs Sonnet 5 가이드에는 모든 주요 변경 사항과 변경 전/후 JSON이 나와 있습니다. 아래의 각 요청을 Apidog에서 보내고 어설션과 함께 저장된 테스트로 유지할 수 있습니다.
Claude Sonnet 5.5 API 요약
| 매개변수 | Sonnet 5.5 동작 |
|---|---|
| 모델 ID | claude-sonnet-5-5 (Bedrock: anthropic.claude-sonnet-5-5) |
| MTok당 가격 | 입력 $2, 출력 $10, 캐시 읽기 $0.20; 배치 $1/$5 |
| 컨텍스트 / 출력 | 1M / 128K; `output-300k-2026-03-24` 베타를 사용한 배치 시 300K |
output_config.effort |
low, medium, high (기본값), xhigh, max |
thinking.type |
adaptive (생략 시 기본값) 또는 between_tools; disabled는 400 반환 |
thinking.display |
omitted (기본값), summarized, updates (베타) |
tool_choice |
auto 또는 none; any 및 tool은 400 반환 |
temperature, top_p, top_k |
기본값이 아닌 값은 400 반환 |
| 최소 캐시 가능 프롬프트 | 512 토큰 (Sonnet 5에서는 1,024) |
에이전트 코딩용 max_tokens |
스트리밍 포함 128,000 |
출처: Sonnet 5.5 모델 페이지 및 마이그레이션 가이드.
Claude Sonnet 5.5 API 예시: 첫 호출
API 키를 생성하고 (Anthropic API 키 가이드에 설명되어 있습니다) 하드코딩하는 대신 `ANTHROPIC_API_KEY`로 내보내십시오. 그런 다음 다음을 보내세요:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"output_config": {"effort": "medium"},
"messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
}'
Python SDK는 환경 변수에서 `ANTHROPIC_API_KEY`를 읽습니다:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
if block.type == "text":
print(block.text)
TypeScript도 동일하게 작동합니다:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 4096,
output_config: { effort: "medium" },
messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
if (block.type === "text") console.log(block.text);
}
`type`별로 콘텐츠 블록을 읽습니다. 사고(thinking)는 기본적으로 활성화되어 있으므로, 응답이 `thinking` 블록으로 시작될 수 있으며 `content[0].text`를 읽는 코드가 오류를 발생시킬 수 있습니다. 사고 토큰은 출력으로 청구되며 텍스트가 숨겨져 있어도 `max_tokens`에 포함되므로, 예상 응답보다 여유 공간을 남겨두십시오.
노력(effort) 수준 선택
`output_config.effort`에 설정된 노력(Effort)은 주요 비용 및 품질 조절 기능입니다. Anthropic은 Sonnet 5.5에 대해 수준을 재조정했으므로 Sonnet 5 설정이 그대로 적용되지 않습니다. 자체 평가를 통해 새로 측정해 보십시오. 프롬프팅 가이드는 다음 시작점을 제안합니다:
| 작업 부하 | 시작 값 |
|---|---|
| 일반 작업 | high (API 기본값) |
| 에이전트 코딩, 잘 명시된 작업 | `medium`, 더 어렵거나 긴 작업에는 `high`로 이동 |
| 채팅 및 지연 시간에 민감한 호출 | `medium` 또는 `low` |
| 평가에서 측정 가능한 이득이 있는 어려운 작업 | `xhigh` 또는 `max` |
편차는 큽니다. Anthropic 자체 Terminal-Bench 4.0 실행에서 Sonnet 5.5는 `high`에서 시도당 $1.94로 43.0%, `max`에서 $12.54로 70.6%를 기록했습니다. Sonnet 5.5 가격 분석은 요청당 비용을 자세히 설명합니다.
세 가지 동작을 계획하십시오. `medium` 이상에서는 모델이 인사말조차 거의 모든 응답 전에 생각하며, 덜 생각하도록 프롬프팅하는 것은 신뢰할 수 없습니다. 대신 노력을 낮추십시오. `low` 및 `medium`에서는 긴 에이전트 작업에서 일찍 확인하는 경향이 있습니다. 그리고 요청 간에 최상위 노력 수준을 변경하면 프롬프트 캐시가 무효화됩니다. 대화 중에 수준을 전환하고 캐시를 유지하려면 메시지별 노력(베타, 헤더 `anthropic-beta: mid-conversation-output-config-2026-07-01`)을 사용하십시오: 빈 `content`와 새 `output_config.effort`를 가진 `role: "system"` 메시지를 추가하십시오.
사고(thinking) 제어: 적응형(adaptive) 또는 도구 간(between_tools)
`thinking` 필드를 생략하면 Sonnet 5.5는 적응형 사고를 실행합니다. `{"type": "disabled"}`는 400 오류와 함께 거부됩니다. 사전 사고(up-front thinking)를 끄려면 가장 낮은 설정인 `between_tools`를 보내십시오:
{
"model": "claude-sonnet-5-5",
"max_tokens": 16000,
"thinking": {"type": "between_tools"},
"output_config": {"effort": "high"},
"messages": [{"role": "user", "content": "..."}]
}
Sonnet 5.5 `between_tools` 규칙:
- `low`, `medium`, `high`에서만 작동합니다. `xhigh` 또는 `max`에서는 400을 반환합니다.
- 다른 필드를 사용하지 않습니다. `display`, `budget_tokens`, `block_binding`을 추가하면 400을 반환합니다.
- 베타 헤더가 필요 없으며 모든 플랫폼에서 작동합니다.
- 설정되어 있는 동안 대화 도중에 노력(effort)을 변경할 수 없습니다.
- 이를 정의하지 않는 SDK 버전은 타입 검사에 실패하므로 SDK를 업데이트하십시오.
적응형 사고(adaptive thinking)에서 `display`는 사고(thinking) 블록이 포함하는 내용을 결정합니다. 기본값인 `omitted`는 각 `thinking` 블록을 빈 `thinking` 필드와 `signature`와 함께 반환합니다. `summarized`는 읽기 쉬운 요약을 반환합니다. `updates` (베타, 헤더 `thinking-display-updates-2026-08-18`)는 진행 상황 업데이트만 텍스트로 반환합니다.
진행 상황 업데이트는 UI를 혼란스럽게 할 가능성이 가장 큰 변경 사항입니다. Sonnet 5.5는 도구 호출 사이에 작성된 한두 문장 이상의 메모를 `text` 대신 자체 `thinking` 블록에 넣습니다. 기본값인 `omitted`에서는 해당 블록이 비어 있으므로, 이전에는 단계를 설명하던 에이전트 인터페이스가 조용해집니다. `display: "updates"` 또는 `"summarized"`로 설정하거나, 텍스트가 포함된 메모를 반환하는 `between_tools`를 실행하십시오. 각 비어있지 않은 `thinking` 블록은 그 뒤에 오는 `tool_use` 블록 전에 렌더링하십시오. 응답 텍스트에 추론을 요청하면 `reasoning_extraction` 거부가 발생할 수 있으므로, 대신 이 블록들을 읽으십시오.
강제 tool_choice 없이 도구 사용
강제 도구 사용 기능은 사라졌습니다. `{"type": "any"}` 또는 `{"type": "tool", ...}`과 같은 `tool_choice`는 토큰 계산 엔드포인트에서도 다음 메시지와 함께 400 오류를 반환합니다:
tool_choice: type "tool" and "any" are not supported for this model.
`auto`를 보내고, 도구의 입력이 스키마와 일치하도록 `strict: true`로 표시하고, 프롬프트에서 모델에게 언제 호출할지 알려주십시오:
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather for a city",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}],
"tool_choice": {"type": "auto"},
"messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}
요청은 최대 20개의 엄격한 도구를 포함할 수 있으며, 엄격한 스키마는 모든 객체에 `additionalProperties: false`가 필요합니다. Amazon Bedrock에서는 Sonnet 5.5에 대해 엄격한 도구를 사용할 수 없습니다. `strict` 없이 `auto`를 보내고 코드에서 입력을 검증하십시오.
두 가지 루프 세부 사항이 중요합니다. 비어 있는 `thinking` 블록을 포함하여 모든 `thinking` 블록을 `tool_use` 블록과 함께 변경하지 않고 다시 전달하십시오. 그리고 `Bash`로 선언된 도구에 대해 `bash`와 같이 가끔 대소문자 오류가 발생할 수 있습니다. 프롬프팅 가이드는 모호하지 않은 일치를 수락하거나 정확한 이름을 명시하는 `is_error: true`가 포함된 `tool_result`를 반환할 것을 제안합니다.
응답 스트리밍
본문에 `\"stream\": true`를 추가하거나 SDK의 스트림 헬퍼를 사용하십시오. 에이전트 코딩의 경우, 프롬프팅 가이드는 스트리밍과 함께 128,000의 `max_tokens`를 권장합니다:
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=128000,
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
for event in stream:
if event.type == "content_block_delta" and event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
final = stream.get_final_message()
서버 전송 이벤트는 `message_start`, 이어서 각 블록에 대해 `content_block_start`, `content_block_delta`, `content_block_stop` 순서로 도착하며, 그 다음 `message_delta` (`stop_reason` 포함)와 `message_stop`이 옵니다. `omitted` 설정에서는 사고(thinking) 블록이 하나의 빈 `thinking_delta`와 `signature_delta`를 스트리밍한 다음 텍스트가 시작됩니다. 진행 상황 업데이트 블록이 열리기 전에 몇 초간 일시 중지가 있을 수 있습니다.
`stream.get_final_message()` (TypeScript: `stream.finalMessage()`)는 서명이 포함된 완전한 블록을 재구성합니다. 해당 콘텐츠를 어시스턴트 차례로 변경하지 않고 기록에 추가하고, 기록은 추가 전용으로 유지하십시오. Sonnet 5.5는 이전 대화에 걸쳐 각 사고(thinking) 블록에 서명하므로, 2026년 8월 31일(UTC 00:00) 이후에 생성된 계정에서는 이전 기록을 편집한 후 블록을 다시 재생하면 400 오류를 반환합니다. 블록은 또한 이를 생성한 계정에 연결됩니다.
거부 및 폴백 처리
거부(refusal)는 오류가 아닙니다. `stop_reason: "refusal"`과 함께 HTTP 200 응답을 받으며, `category`가 `cyber`, `bio`, `frontier_llm`, `reasoning_extraction`, `general_harms` 중 하나인 `stop_details` 객체와 `explanation`이 함께 제공됩니다. 설명을 파싱하는 대신 그대로 표시하십시오. 그 문구는 안정적이지 않습니다. `content`를 읽기 전에 `stop_reason`에 따라 분기하십시오.
서버 측 폴백은 선택 사항입니다. `\"fallbacks\": "default"`와 `anthropic-beta: server-side-fallback-2026-07-01` 헤더(베타, Claude API만 해당)를 추가하면, API는 Sonnet 5에서 `cyber` 및 `frontier_llm` 거절을 재시도합니다. 다른 세 가지 카테고리는 재시도되지 않습니다. 응답의 `model` 필드는 서비스를 제공한 모델의 이름을 나타내며, `fallback` 콘텐츠 블록은 핸드오프를 표시합니다.
속도 제한
Sonnet 5.5는 Sonnet 5와 별개로 자체 속도 제한을 가집니다. 속도 제한 페이지에는 네 가지 티어가 나열되어 있습니다:
| 티어 | 분당 요청 수 | 분당 입력 토큰 수 | 분당 출력 토큰 수 |
|---|---|---|---|
| 시작 (Start) | 1,000 | 2,000,000 | 400,000 |
| 빌드 (Build) | 5,000 | 5,000,000 | 1,000,000 |
| 확장 (Scale) | 10,000 | 10,000,000 | 2,000,000 |
| 커스텀 (Custom) | 영업팀 문의 | 영업팀 문의 | 영업팀 문의 |
429 처리 및 백오프에 대해서는 속도 제한 초과 가이드를 참조하십시오.
Apidog에서 Claude Sonnet 5.5 API 테스트
저장된 요청은 노력(effort) 비교 및 스트림 디버깅을 반복 가능하게 만듭니다. 다음은 Apidog에서 설정하는 방법입니다:
- 환경을 생성하고 `ANTHROPIC_API_KEY`를 변수로 추가하십시오. `x-api-key` 헤더에서 `anthropic-version` 및 `content-type` 옆에 `{{ANTHROPIC_API_KEY}}`로 참조하십시오.
- `https://api.anthropic.com/v1/messages`로 POST 요청을 생성하고, 첫 호출 본문을 붙여넣고 저장하십시오.
- 어설션을 추가하십시오: 상태는 200, `$.stop_reason`은 `end_turn`과 같고, `$.usage.output_tokens`는 0보다 크며, `$.content[*].type`에는 `text`가 포함되어야 합니다. 이제 거부(refusal)는 조용히 통과하는 대신 테스트를 실패시킵니다.
- `"stream": true`를 사용하여 요청을 복제하십시오. Apidog는 `text/event-stream` 응답 이벤트를 이벤트별로 표시하므로, 빈 `thinking_delta`, `signature_delta`, 텍스트가 순서대로 도착하는 것을 볼 수 있습니다.
- `"model": "claude-sonnet-5"`로 다시 복제하고 한 폴더에 두 요청을 보관하십시오: 동일한 프롬프트, 두 모델, `usage`를 나란히 비교할 수 있습니다.
더 넓은 패턴에 대해서는 LLM 애플리케이션 테스트 및 AI 에이전트 API 테스트를 참조하십시오.
자주 묻는 질문
- Claude Sonnet 5.5 모델 ID는 무엇인가요? Claude API, Google Cloud, Microsoft Foundry 및 AWS의 Claude Platform에서는 날짜 접미사 없이 `claude-sonnet-5-5`입니다. Amazon Bedrock에서는 `anthropic.claude-sonnet-5-5`입니다.
- 사고(thinking)를 완전히 끌 수 있나요? 아니요. `disabled`는 400 오류를 반환합니다. `between_tools`는 가장 낮은 설정으로, `low`, `medium`, `high` 노력(effort) 수준에서 사전 사고(up-front thinking)가 없습니다.
- Sonnet 5 요청이 Sonnet 5.5에서 400 오류를 반환하는 이유는 무엇인가요? 먼저 `thinking.type: "disabled"`와 강제 `tool_choice`가 있는지 확인하십시오. Sonnet 5.5 vs Sonnet 5 가이드에서 다섯 가지 주요 변경 사항과 해결 방법을 다룹니다.
- 무료 Claude Sonnet 5.5 API가 있나요? Anthropic의 API는 선불이며, 공식 페이지에 무료 가입 크레딧이 명시되어 있지 않습니다. Claude 채팅 플랜에도 API 접근은 포함되지 않습니다. 무료 API 가이드는 크레딧 프로그램과 가장 저렴한 유료 경로를 다룹니다.
다음 단계
첫 호출 요청을 `medium`으로 보낸 다음, `high`로 다시 실행하여 자체 작업 부하의 프롬프트에 대한 `usage.output_tokens` 및 답변 품질을 비교하십시오. Apidog 다운로드하여 두 실행 결과를 어설션과 함께 저장하십시오. 터미널에서 작업하고 싶다면, Claude Code의 Claude Sonnet 5.5를 참조하십시오.