Claude API를 호출할 때 model 파라미터에 무엇을 넣어야 할까요? 그리고 claude-opus-5 같은 ID와 claude-haiku-4-5 같은 별칭(alias)은 무엇이 다를까요? 이 글은 API에서의 모델 ID·버전 관리를 다룹니다. (모델 계열별 성능·용도 비교는 모델 비교 글, SDK 설치·첫 호출은 SDK 가이드를 참고하세요. 이 글은 그 사이, "어떤 문자열을 어떻게 관리하나"에 집중합니다.) 기준 시점: 2026년 9월(model-ids-and-versions·models overview 문서 재대조), 출처: Claude 공식 문서.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
2026년 9월 27일 업데이트: 2026년 9월 22일 Claude Opus 5.5가 출시되어 현행 Opus 모델이 됐습니다(API claude-opus-5-5, 입력 100만 토큰당 $4·출력 $20 — Opus 5의 $5/$25보다 낮음). Anthropic은 대부분의 작업에서 Fable 5.1 수준 성능을 내면서 일반 작업 기준 Opus 5보다 40% 저렴하다고 밝혔습니다. Opus 5는 계속 제공되지만 공식 모델 문서에서 레거시로 표기됩니다. 아래 본문의 Opus 5 가격·비교 서술은 발표 이전 기준이며 순차 갱신 예정입니다. 자세한 내용: Claude Opus 5.5 완벽 가이드.
모든 모델 ID는 "고정 스냅숏"이다
공식 문서에 따르면 모든 Claude 모델 ID는 고정 스냅숏(pinned snapshot)입니다. ID에 날짜가 들어간 경우(예: ...20250929)는 그 특정 릴리스에 고정됩니다. 즉 같은 ID를 쓰는 한, 같은 모델 가중치(weights)를 받습니다.
날짜 없는 ID도 고정이다 (흔한 오해)
Claude 4.6 세대부터 모델 ID는 날짜 없는 형식(예: claude-opus-5, claude-sonnet-4-6)을 씁니다. 흔한 오해는 "claude-sonnet-4-6 같은 날짜 없는 ID가 항상 최신/최고 버전으로 라우팅된다"고 생각하는 것입니다. 사실이 아닙니다. 4.6 세대부터 날짜 없는 ID는 그 릴리스의 표준(canonical) ID이자 단일 고정 스냅숏입니다. Anthropic은 기존 ID의 가중치·설정을 바꾸지 않으며, 업데이트 버전은 항상 새 ID로 출시합니다.
모델 가중치는 ID에 고정되지만, 모델 주변의 서빙 인프라(요청 라우터·안전 분류기·샘플링 로직 등)는 시간이 지나며 바뀔 수 있고, 가끔 ID·가중치가 그대로여도 관측되는 동작에 미세한 차이가 생길 수 있습니다(공식 문서).
alias는 "편의 포인터"다 (변할 수 있음)
별칭(alias)은 다릅니다. 공식 문서 기준 Claude API의 별칭은 4.6 이전 세대 모델에만 있으며, claude-sonnet-4-5·claude-haiku-4-5처럼 날짜를 뺀 이름이 해당 minor 버전의 가장 최근 날짜 스냅숏(예: claude-haiku-4-5-20251001)으로 연결되는 편의 포인터입니다. 4.6 세대부터는 날짜 없는 ID(claude-opus-5 등)가 곧 스냅숏이라 별칭이 따로 없습니다. (opus·sonnet 같은 한 단어 이름은 Claude Code의 /model 명령용이지 API의 model 값이 아닙니다.) 별칭이 가리키는 대상은 새 날짜 스냅숏이 나오면 바뀝니다. 편리하지만, 프로덕션에서는 어느 날 코드 변경 없이 모델이 바뀌어 동작이 달라질 수 있다는 뜻이기도 합니다.
프로덕션은 버전을 고정(pin)하라
그래서 권장 패턴은 명확합니다. 개발·실험·일회성 스크립트에는 alias가 편하고, 프로덕션·재현성이 중요한 곳에서는 전체 모델 ID로 고정하세요.
# 고정(pin): 전체 모델 ID — 항상 같은 스냅숏
message = client.messages.create(
model="claude-opus-5", # 고정 스냅숏
max_tokens=1024,
messages=[{"role": "user", "content": "안녕"}],
)
# alias: 편의 포인터 — 권장 버전으로 자동 연결(시간에 따라 바뀔 수 있음)
message = client.messages.create(
model="claude-haiku-4-5", # 별칭(4.6 이전 세대) — 개발·실험용
max_tokens=1024,
messages=[{"role": "user", "content": "안녕"}],
)업데이트와 deprecation 대비
모든 모델 ID(날짜 있든 없든)는 각자 고유한 deprecation·retirement 일정을 가집니다. 고정 ID를 쓰면 동작은 안정적이지만, 해당 모델이 은퇴 예정이 되면 새 ID로 옮기는 마이그레이션이 필요합니다. 팀이라면 전환 날짜·모델 버전·프롬프트 조정 내역을 기록해 두면 나중에 동작 변화를 진단할 때 도움이 됩니다. 일정은 공식 모델 개요와 deprecation 문서에서 확인하세요.
Models API로 조회하기
어떤 모델이 쓸 수 있고, 컨텍스트·출력 한도가 얼마인지는 Models API로 코드에서 직접 조회할 수 있습니다. 하드코딩한 표를 관리하는 대신, 런타임에 질의하면 항상 최신입니다.
# 사용 가능한 모델과 능력·토큰 한도를 코드로 조회
models = client.models.list() # 목록
m = client.models.retrieve("claude-opus-5")
m.id # "claude-opus-5"
m.display_name # "Claude Opus 5"
m.max_input_tokens # 컨텍스트 윈도우(정수)
m.max_tokens # 최대 출력 토큰(정수)정리
핵심: ① 모든 모델 ID는 고정 스냅숏 ② 4.6 세대부터 날짜 없는 ID도 고정(최신 자동연결 아님) ③ 별칭(claude-haiku-4-5 등, 4.6 이전 세대만)은 변할 수 있는 편의 포인터 ④ 프로덕션은 전체 ID로 고정 ⑤ 업데이트는 새 ID로 오므로 deprecation·마이그레이션 대비 ⑥ Models API로 가용 모델·한도를 코드로 조회.
더 알아보기: 한 요청이 다룰 수 있는 용량과 토큰 관리법은 컨텍스트 윈도우와 토큰 가이드를 참고하세요.
모델 ID 목록·alias 매핑·가용 범위는 시점과 배포처(Claude API, AWS, Vertex, Foundry)에 따라 다를 수 있습니다. 프로덕션 반영 전 반드시 공식 모델 문서에서 최신 ID와 deprecation 일정을 확인하세요.