Anthropic Claude 모델 패밀리 & Messages API 심화 리서치 원본 — 2026-07-25

불변 캡처. 절대 편집하지 마라. 가공본은 위키 페이지에. 기준: 규격서 §7 (Anthropic first-party [HIGH]) 이 진실. 웹은 §7 보강용. 충돌 시 §7 우선, 충돌 사실은 "엇갈리거나 미확인" 에 기록.

조사 방법

검색어

• "Anthropic Claude models overview platform.claude.com docs"
• "Anthropic Messages API tool use documentation platform.claude.com"
• "Anthropic prompt caching documentation platform.claude.com"

열어본 URL (WebFetch, 총 7개)

1. https://platform.claude.com/docs/en/about-claude/models/overview.md — 모델 라인업/스펙 표
2. https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview — tool use 루프, 서버/클라이언트 툴
3. https://platform.claude.com/docs/en/build-with-claude/prompt-caching — 프롬프트 캐싱
4. https://platform.claude.com/docs/en/api/errors — 에러코드
5. https://platform.claude.com/docs/en/build-with-claude/streaming — SSE 스트리밍
6. https://platform.claude.com/docs/en/build-with-claude/batch-processing — 배치 API
7. https://platform.claude.com/docs/en/build-with-claude/structured-outputs — 구조화 출력
8. https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner — Tool Runner

전부 first-party 도메인 platform.claude.com. 따라서 아래 사실은 §7 과 함께 [HIGH].

확인된 사실 [신뢰도]

1. 모델 라인업 — 포지셔닝 (platform.claude.com/docs/en/about-claude/models/overview) [HIGH]

공식 "Choosing a model" 문구 (직접 인용):

"If you're unsure which model to use, start with Claude Opus 5 for complex agentic coding and enterprise work. For workloads that need the highest available capability, use Claude Fable 5."

공식 최신 4모델 비교표의 Description 열 (직접 인용) [HIGH]: - Claude Fable 5 (claude-fable-5): "Next-generation intelligence for long-running agents" / "Anthropic's most capable widely released model" / latency = Slower / 1M ctx / 128K out / $10·$50 / knowledge cutoff Jan 2026. GA 2026-06-09 (Claude API, Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry). - Claude Opus 5 (claude-opus-5): "For complex agentic coding and enterprise work" / latency = Moderate / 1M ctx / 128K out / $5·$25 / knowledge cutoff May 2026 (라인업 중 최신). 기본값 권장. - Claude Sonnet 5 (claude-sonnet-5): "The best combination of speed and intelligence" / latency = Fast / 1M ctx / 128K out / $3·$15 (인트로 $2·$10, 2026-08-31까지) / knowledge cutoff Jan 2026. - Claude Haiku 4.5 (claude-haiku-4-5, 풀 ID claude-haiku-4-5-20251001): "The fastest model with near-frontier intelligence" / latency = Fastest / 200K ctx / 64K out / $1·$5 / knowledge cutoff Feb 2025.

Claude Mythos 5 (claude-mythos-5): Fable 5 와 스펙·가격 동일. GA 아님 — Project Glasswing 초대 전용 (invitation-only, self-serve 없음). 방어적 사이버보안 워크플로우용. claude-mythos-preview 는 별개의 프리뷰 모델 ID. [HIGH]

Legacy(여전히 사용 가능, 마이그레이션 권장) 표 [HIGH]: - Claude Opus 4.8 (claude-opus-4-8): Moderate / 1M / 128K / $5·$25 / cutoff Jan 2026. - Claude Opus 4.7 (claude-opus-4-7): Moderate / 1M / 128K / $5·$25 / cutoff Jan 2026. Opus 4.7 부터 새 tokenizer (같은 텍스트가 4.7 이전 대비 약 30% 더 많은 토큰 생성 — Fable 5 도 이 tokenizer 사용). - Claude Opus 4.6 (claude-opus-4-6): Moderate / 1M / 128K / $5·$25 / cutoff May 2025. - Claude Sonnet 4.6 (claude-sonnet-4-6): Fast / 1M / 128K / $3·$15 / cutoff Aug 2025. - (더 이전: Sonnet 4.5 claude-sonnet-4-5-20250929, Opus 4.5 claude-opus-4-5-20251101, Opus 4.1 claude-opus-4-1-20250805 — Opus 4.1 은 deprecated, 2026-08-05 은퇴 예정.)

2. 모델 ID·버전 규칙 [HIGH]

• 모든 Claude 모델 ID 는 pinned snapshot. 날짜 있는 ID(예 20250929)는 그 릴리스에 고정.
• 4.6 세대부터 dateless 포맷(claude-opus-4-6)도 pinned snapshot (evergreen 포인터 아님). 4.6 이전 세대의 alias 열은 dated ID 로 resolve 되는 편의 포인터.
• Haiku 4.5 는 예외적으로 풀 dated ID claude-haiku-4-5-20251001 존재 (alias claude-haiku-4-5). → §7 재확인.
• Models API (/docs/en/api/models/list) 로 capabilities/토큰 한도 프로그램적 조회 가능: 응답에 max_input_tokens, max_tokens, capabilities 객체 포함.

3. thinking·effort 노브 [HIGH — 공식 표 + §7]

공식 모델 표의 thinking 열 [HIGH]: | 모델 | Extended thinking (thinking.type:"enabled") | Adaptive thinking | |---|---|---| | Fable 5 | No | Yes (always on) | | Opus 5 | No | Yes | | Sonnet 5 | No | Yes | | Haiku 4.5 | Yes | No | | Opus 4.8 | No | Yes | | Opus 4.7 | No | Yes | | Opus 4.6 | Yes (deprecated) | Yes | | Sonnet 4.6 | Yes (deprecated) | Yes | | Sonnet 4.5 / Opus 4.5 이하 | Yes | No |

• thinking: {type:"adaptive"} 가 현행. §7: budget_tokens 는 Opus 4.7/4.8/5, Fable 5, Sonnet 5 에서 400 에러. Opus 4.6/Sonnet 4.6 에서 deprecated.
• 에러 문구 (errors 페이지, 직접 인용) [HIGH]:
• Claude 4.7+ 에 thinking:{"type":"enabled"} → 400: "\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."
• Claude 4.5 이하에 {"type":"adaptive"} → 400: "adaptive thinking is not supported on this model" (이들은 {"type":"enabled","budget_tokens":N} 사용).
• Fable 5 / Mythos 5 / Mythos Preview 에 {"type":"disabled"} → 400: "\"thinking.type.disabled\" is not supported for this model...". Fable/Mythos 5 는 에러가 권하는 enabled 도 거부 → thinking 필드 자체를 생략해야 adaptive 로 동작. thinking 내용을 응답에서 빼려면 display:"omitted".
• effort: output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"}. 공식 노트 (직접 인용) [HIGH]: "On Claude Opus 4.8, the effort parameter defaults to high on all surfaces... On Claude Opus 5 and Claude Sonnet 5, it defaults to high on the Claude API and Claude Code." → 기본값 high, §7 재확인. xhigh 는 Opus 4.7 부터, 코딩/에이전트 권장. Opus 5 는 low/medium 이 유난히 강함(§7).
• thinking blocks 수정 금지 (errors, 직접 인용) [HIGH]: 최근 assistant 메시지의 thinking/redacted_thinking 블록을 편집/재정렬/필터/재구성해서 되돌려보내면 400. tool use 시 assistant 턴의 모든 thinking/redacted_thinking 블록을 받은 그대로(빈 것 포함) 다시 넣어야 함.

4. prefill 금지 (errors 페이지) [HIGH]

• Claude 4.6+ 및 Mythos Preview 는 assistant 메시지 prefill 미지원. 마지막 턴 prefill 요청 → 400 "This model does not support assistant message prefill. The conversation must end with a user message."
• 대안: structured outputs (output_config.format), system 프롬프트 지시. → §7 재확인.

5. Tool use 루프 (tool-use/overview) [HIGH]

• Claude 가 툴 호출 판단 → stop_reason: "tool_use" + 하나 이상의 tool_use 블록 반환. 앱이 실행 후 tool_result 블록으로 되돌려보냄(다음 요청). Claude 가 결과로 최종 답변.
• 클라이언트 툴(user 정의 + Anthropic 스키마 툴 bash/text_editor/memory/computer): 앱에서 실행.
• 서버 툴(web_search, web_fetch, code_execution, advisor, tool_search): Anthropic 인프라에서 실행, 결과가 같은 응답에 직접 옴 (단 같은 병렬 그룹에 클라이언트 툴이 섞이면 예외).
• 툴 정의: name, description, input_schema (JSON Schema, type:"object" + properties + required).
• tool_choice: 기본 {"type":"auto"} (턴마다 자율 판단). {"type":"any"} (아무 툴이나 강제), {"type":"tool", ...} (특정 툴 강제), {"type":"none"}. disable_parallel_tool_use: true 로 턴당 최대 1개 툴 호출 제한.
• tool_result 블록: {"type":"tool_result", "tool_use_id": <id>, "content": <결과>}. user 롤 메시지 안에 넣음.
• 툴 호출 유도는 system 프롬프트로 조종 가능 ("Use the tools to investigate before responding." 등).
• 파라미터 누락 시: Opus 는 누락 인지하고 되물을 확률 높음, Sonnet 은 값을 추측(infer)할 수 있음.
• strict tool use: 커스텀 툴 정의에 strict: true (top-level 필드) 추가 → 툴 호출이 스키마에 정확히 부합 보장. 스키마에 additionalProperties: false + required 필요. → §7 재확인.

6. Tool use 시스템 프롬프트 토큰 오버헤드 (tool-use/overview, 직접 인용 표) [HIGH]

tools 사용 시 API 가 툴 활성화용 특수 system 프롬프트 자동 주입 (툴 최소 1개 가정, tool_use/tool_result 블록 토큰은 별도): | 모델 | auto/none | any/tool | |---|---|---| | Opus 5 | 286 | 406 | | Opus 4.8 | 290 | 410 | | Opus 4.7 | 675 | 804 | | Opus 4.6 | 497 | 589 | | Sonnet 5 | 354 | 474 | | Sonnet 4.6 | 497 | 589 | | Haiku 4.5 | 496 | 588 | (tools 없거나 tool_choice: none + 툴 없음 → 0 토큰.)

7. 서버 툴 pricing [HIGH]

• 서버 툴은 토큰 위에 usage 기반 추가 과금 (예: web_search 는 검색당 과금). 클라이언트 툴은 일반 요청과 동일 과금.
• §7: 서버 툴 최신 버전 web_search_20260209, web_fetch_20260209(동적 필터링 내장 — code_execution 별도 선언 불필요), code_execution_20260521, tool_search_tool_regex_20251119 / tool_search_tool_bm25_20251119.
• (주의: streaming 문서 예제는 구버전 web_search_20250305 사용. tool-use overview 예제는 web_search_20260209 사용. 최신은 20260209 — §7 우선.)

8. Tool Runner (tool-use/tool-runner) [HIGH]

• 베타. 에이전틱 루프·에러 래핑·타입 안전·대화 상태 관리를 자동 처리. human-in-the-loop 승인/커스텀 로깅/조건부 실행이 필요하면 수동 루프 사용.
• Python: @beta_tool 데코레이터(함수 인자+docstring 에서 JSON 스키마 자동 도출) + client.beta.messages.tool_runner(...). runner 를 이터레이트하면 각 메시지가 나옴.
• TypeScript: betaZodTool({name, description, inputSchema: z.object({...}), run: async(input)=>...}) (Zod ≥3.25.0 권장) 또는 betaTool() (JSON Schema, 런타임 검증 없음) + client.beta.messages.toolRunner(...).
• 다른 SDK 도 지원: C#, Go, Java, PHP, Ruby.
• 툴은 문자열 또는 content block(text/image/document) 반환 가능 → 멀티모달 결과. 구조화 데이터는 문자열로 인코딩해서 반환.
• §7: Tool Runner ≠ Agent SDK. Agent SDK(claude-agent-sdk/@anthropic-ai/claude-agent-sdk)는 Claude Code 를 라이브러리화한 별개 제품(내장 툴 포함). Tool Runner 는 일반 SDK 안의 루프 헬퍼(내장 툴 없음).

Python 예제 (문서 발췌):

@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.
    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[{"role":"user","content":"What's the weather in Paris? Also 15+27?"}],
)
for message in runner:
    print(message)

9. 구조화 출력 (structured-outputs) [HIGH]

• 두 기능: (a) JSON outputs output_config.format (b) strict tool use strict:true.
• output_config: {format: {type: "json_schema", schema: {...}}}. 스키마에 additionalProperties: false + required. → §7 재확인 (구버전 top-level output_format 은 deprecated, 베타 헤더 structured-outputs-2025-11-13 + output_format 은 전환기 동안 계속 동작).
• SDK 메서드:
• Python: client.messages.parse(..., output_format=PydanticModel) → response.parsed_output (typed 객체). Pydantic 모델을 JSON 스키마로 자동 변환·검증.
• TypeScript: client.messages.parse({..., output_config: {format: zodOutputFormat(ZodSchema)}}) (@anthropic-ai/sdk/helpers/zod).
• Java outputConfig(Class<T>), Ruby Anthropic::BaseModel, PHP StructuredOutputModel.
• 지원 모델 (Claude API GA): Opus 5, Mythos Preview, Claude 4.5 이상. (Bedrock/Vertex 는 별도 목록.)
• JSON Schema 지원: basic types, enum, const, anyOf, allOf, $ref, string format(date-time/date/email/uuid/uri/ipv4/ipv6), additionalProperties:false, required, minItems(0 또는 1만).
• 미지원: 재귀 스키마, 외부 $ref(HTTP URL), 숫자 제약(minimum/maximum/multipleOf), 문자열 제약(minLength/maxLength), additionalProperties 를 false 이외 값으로.
• 문법 컴파일 캐싱: 스키마 첫 사용 시 추가 지연, grammar 는 24시간 캐시. output_config.format 이나 툴셋 변경은 프롬프트 캐시 무효화.

10. 프롬프트 캐싱 (prompt-caching) [HIGH — §7 와 완전 일치]

• cache_control 배치: top-level(자동 캐싱, 1 slot 사용) 또는 블록 단위(명시 breakpoint).
• 최소 캐시 가능 토큰 (모델별, 단조증가 아님) — §7 과 doc 일치:
• Opus 5 / Fable 5 / Mythos 5 = 512
• Opus 4.8 / Sonnet 5 / Sonnet 4.6 / Sonnet 4.5 / Opus 4.1 / Opus 4 / Sonnet 4 = 1,024
• Mythos Preview / Opus 4.7 = 2,048 (Haiku 3.5 도 2,048)
• Opus 4.6 / Opus 4.5 / Haiku 4.5 = 4,096
• (미달 프롬프트는 cache_control 있어도 캐시 안 됨, 에러는 없음.)
• TTL: 5분 기본 {"type":"ephemeral"}, 1시간 {"type":"ephemeral","ttl":"1h"}.
• 가격 배수: 5분 캐시 쓰기 = base 입력 ×1.25 / 1시간 쓰기 = ×2 / 캐시 읽기(둘 다) = ×0.1. → §7 재확인.
• 최대 breakpoint 4개 (자동 캐싱이 1개 소비). 렌더 순서 tools → system → messages.
• lookback window: 이전 캐시 항목 재사용을 위해 최대 20개 position(블록) 확인.
• 응답 usage: cache_creation_input_tokens, cache_read_input_tokens, input_tokens. 총 입력 = 세 값 합.
• thinking 블록은 명시 cache_control 불가하나 이전 assistant 턴에서 다른 콘텐츠와 함께 캐시됨.
• mid-conversation system message: Fable 5 / Mythos 5 / Opus 4.8 / Opus 5 에서 messages 안 {"role":"system"} 을 system 캐시 무효화 없이 추가 가능. (§7: Sonnet 5 는 미지원. 베타 헤더 불필요.)

11. 스트리밍 SSE (streaming) [HIGH]

• "stream": true. 이벤트 흐름: 1. message_start (빈 content 의 Message) 2. content block 마다: content_block_start → content_block_delta(여러 개) → content_block_stop (각 block 은 index 보유) 3. message_delta(여러 개, 최상위 변경 — stop_reason 등. usage 는 누적) 4. message_stop
• 중간에 ping 이벤트 가능. error 이벤트 가능(200 후 mid-stream, 예 overloaded_error).
• delta 타입: text_delta(.text), input_json_delta(.partial_json — 부분 JSON 문자열, block_stop 후 파싱), thinking_delta(.thinking), signature_delta(.signature, thinking block_stop 직전 무결성 서명).
• display:"omitted" 시 thinking_delta 없음 — thinking block 이 열리고 signature_delta 하나 받고 닫힘.
• 서버 툴 스트리밍: server_tool_use block + web_search_tool_result block 등장.
• SDK 헬퍼: Python client.messages.stream(...) as stream: stream.text_stream / stream.get_final_message(). TS .stream().on("text",...) / .finalMessage(). Go message.Accumulate(event). Java MessageAccumulator. Ruby .accumulated_message. C# .Aggregate().
• 대용량 max_tokens 는 스트리밍 필수 (SDK 는 비스트리밍 요청이 10분 timeout 초과 예상되면 검증 거부). §7: 비스트리밍 ~16000, 스트리밍 ~64000 권장, 128K 출력은 반드시 스트리밍.
• Error recovery: Claude 4.5 이하 = 부분 응답을 assistant 메시지로 넣어 재개. Claude 4.6+ = user 메시지로 "이어서 계속" 지시 (prefill 미지원 때문). tool_use/thinking 블록은 부분 복구 불가, 최근 text 블록부터 재개.

12. 배치 API (batch-processing) [HIGH]

• 50% 할인 (모든 usage 가 표준가의 50%). 예: Opus 5 = 배치 입력 $2.50 / 출력 $12.50. Sonnet 5 = $1/$5 (인트로, 9/1부터 $1.50/$7.50). Haiku 4.5 = $0.50/$2.50.
• 한 배치 한도: 100,000 요청 또는 256MB 중 먼저 도달. (요청 크기 한도: Messages API 32MB, Batch API 256MB.)
• 대부분 1시간 내 완료. 결과는 전부 완료 또는 24시간 중 먼저. 24시간 내 미완이면 만료(expire).
• 결과 29일 보관 (이후 Batch 는 보이나 다운로드 불가). → §7 재확인.
• custom_id 필수 (1~64자, ^[a-zA-Z0-9_-]{1,64}$). params 는 표준 Messages 파라미터.
• 결과 순서 보장 없음 (직접 인용): "Batch results can be returned in any order, and may not match the ordering of requests... always use the custom_id field." → §7 재확인.
• processing_status: in_progress → ended. request_counts: succeeded/errored/canceled/expired. 결과는 results_url 에서 .jsonl 스트리밍.
• 결과 4타입: succeeded, errored(과금 안 됨), canceled(과금 안 됨), expired(24h 초과, 과금 안 됨).
• 각 요청 max_tokens ≥ 1 필수. max_tokens:0(캐시 pre-warming) 배치 미지원.
• 배치 미지원 파라미터: stream:true, speed(Fast mode), store/previous_thread_event_id(Threads), cache_hint/context_hint, max_tokens:0, research_preview_2026_02.
• 확장 출력: Opus 5/4.8/4.7/4.6, Sonnet 5/4.6 는 배치에서 output-300k-2026-03-24 베타 헤더로 최대 300K 출력. 캐싱은 배치에서 best-effort.

13. 에러코드 (api/errors) [HIGH]

14. stop_reason (§7 + streaming 예제 확인) [HIGH]

• 값: end_turn max_tokens stop_sequence tool_use pause_turn refusal.
• streaming 예제에서 message_delta.delta.stop_reason 로 end_turn, tool_use 확인됨.
• §7: refusal 일 때만 stop_details 채워짐(다른 경우 null — 가드 필요). pause_turn = 서버 툴 루프 10회 한도 → assistant 응답 그대로 붙여 재요청(“계속해” user 메시지 추가 금지).

15. 플랫폼 (§7 + overview) [HIGH]

• Bedrock ID = anthropic. 접두사 (anthropic.claude-opus-5...). Google Cloud/Vertex = 접두사 없음 (claude-opus-5). Claude Platform on AWS = Claude API 와 동일 ID(claude-opus-4-6), Anthropic 운영, 당일 기능 패리티.
• Bedrock/Google Cloud 엔드포인트 타입: global/regional (+Google multi-region). Sonnet 4.5 이후 global+regional.

엇갈리거나 미확인

• web_search 툴 버전 불일치: streaming 문서 예제는 web_search_20250305, tool-use overview 예제는 web_search_20260209. §7 은 최신 = web_search_20260209/web_fetch_20260209 라 명시 → §7 우선. streaming 예제가 오래된 스냅샷.
• 프롬프트 캐싱 최소 토큰: doc 과 §7 완전 일치 확인 (충돌 없음). 단 doc 은 Mythos Preview=2048, Haiku 3.5=2048 도 추가 명시 (§7 에 없던 세부).
• structured outputs 지원 모델: doc "Claude API: Opus 5, Mythos Preview, Claude 4.5 이상" — Fable 5 가 Claude API GA 목록에 명시 안 됨(Vertex 목록엔 있음). Fable 5 의 Claude API structured output 지원 여부는 doc 문면상 불명확 (미확인).
• Sonnet 5 mid-conversation system message: §7 은 "Sonnet 5 미지원", prompt-caching doc 은 지원 모델로 Fable5/Mythos5/Opus4.8/Opus5 만 나열(Sonnet 5 언급 없음) → §7 과 일치(Sonnet 5 제외). 충돌 아님.
• temperature/top_p/top_k: §7 은 Opus 4.7/4.8/5·Fable 5 에서 400, Sonnet 5 비기본값이면 400 이라 명시. 이번 웹 조사에서 별도 확인 페이지는 안 열음 (§7 신뢰).
• 벤치마크 점수: 규격상 인용 안 함. doc 은 정성 표현만("near-frontier", "best combination of speed and intelligence").

원문 발췌 (핵심 직접 인용)

• Model choice: "start with Claude Opus 5 for complex agentic coding and enterprise work. For workloads that need the highest available capability, use Claude Fable 5." (models/overview)
• Effort 기본값: "On Claude Opus 5 and Claude Sonnet 5, it defaults to high on the Claude API and Claude Code. Set effort explicitly to use a different level." (models/overview)
• Prefill 400: "This model does not support assistant message prefill. The conversation must end with a user message." (api/errors)
• thinking.enabled 400: "\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior." (api/errors)
• 배치 순서: "Batch results can be returned in any order, and may not match the ordering of requests when the batch was created... always use the custom_id field." (batch-processing)
• 캐시 순서: "Prompt caching references the entire prompt - tools, system, and messages (in that order) up to and including the block designated with cache_control." (prompt-caching)