Claude API를 호출할 때 model 파라미터에 무엇을 넣어야 할까요? 그리고 claude-opus-4-8 같은 ID와 opus 같은 짧은 이름은 무엇이 다를까요? 이 글은 API에서의 모델 ID·버전 관리를 다룹니다. (모델 계열별 성능·용도 비교는 모델 비교 글, SDK 설치·첫 호출은 SDK 가이드를 참고하세요. 이 글은 그 사이, "어떤 문자열을 어떻게 관리하나"에 집중합니다.) 기준 시점: 2026년 6월, 출처: Claude 공식 문서.
모든 모델 ID는 "고정 스냅숏"이다
공식 문서에 따르면 모든 Claude 모델 ID는 고정 스냅숏(pinned snapshot)입니다. ID에 날짜가 들어간 경우(예: ...20250929)는 그 특정 릴리스에 고정됩니다. 즉 같은 ID를 쓰는 한, 같은 모델 가중치(weights)를 받습니다.
날짜 없는 ID도 고정이다 (흔한 오해)
Claude 4.6 세대부터 모델 ID는 날짜 없는 형식(예: claude-opus-4-8, claude-sonnet-4-6)을 씁니다. 흔한 오해는 "claude-sonnet-4-6 같은 날짜 없는 ID가 항상 최신/최고 버전으로 라우팅된다"고 생각하는 것입니다. 사실이 아닙니다. 4.6 세대부터 날짜 없는 ID는 그 릴리스의 표준(canonical) ID이자 단일 고정 스냅숏입니다. Anthropic은 기존 ID의 가중치·설정을 바꾸지 않으며, 업데이트 버전은 항상 새 ID로 출시합니다.
모델 가중치는 ID에 고정되지만, 모델 주변의 서빙 인프라(요청 라우터·안전 분류기·샘플링 로직 등)는 시간이 지나며 바뀔 수 있고, 가끔 ID·가중치가 그대로여도 관측되는 동작에 미세한 차이가 생길 수 있습니다(공식 문서).
alias는 "편의 포인터"다 (변할 수 있음)
별칭(alias)은 다릅니다. 예를 들어 opus는 현재 권장 Opus 버전으로, sonnet은 권장 Sonnet 버전으로 연결됩니다. (4.6 이전 모델의 경우, Claude API의 alias 열은 해당 minor 버전의 가장 최근 dated 스냅숏으로 resolve되는 편의 포인터였습니다.) alias가 가리키는 대상은 시간이 지나며 바뀝니다. 편리하지만, 프로덕션에서는 어느 날 코드 변경 없이 모델이 바뀌어 동작이 달라질 수 있다는 뜻이기도 합니다.
프로덕션은 버전을 고정(pin)하라
그래서 권장 패턴은 명확합니다. 개발·실험·일회성 스크립트에는 alias가 편하고, 프로덕션·재현성이 중요한 곳에서는 전체 모델 ID로 고정하세요.
# 고정(pin): 전체 모델 ID — 항상 같은 스냅숏
message = client.messages.create(
model="claude-opus-4-8", # 고정 스냅숏
max_tokens=1024,
messages=[{"role": "user", "content": "안녕"}],
)
# alias: 편의 포인터 — 권장 버전으로 자동 연결(시간에 따라 바뀔 수 있음)
message = client.messages.create(
model="opus", # 개발·실험용
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-4-8")
m.id # "claude-opus-4-8"
m.display_name # "Claude Opus 4.8"
m.max_input_tokens # 컨텍스트 윈도우(정수)
m.max_tokens # 최대 출력 토큰(정수)정리
핵심: ① 모든 모델 ID는 고정 스냅숏 ② 4.6 세대부터 날짜 없는 ID도 고정(최신 자동연결 아님) ③ alias(opus·sonnet 등)는 변할 수 있는 편의 포인터 ④ 프로덕션은 전체 ID로 고정 ⑤ 업데이트는 새 ID로 오므로 deprecation·마이그레이션 대비 ⑥ Models API로 가용 모델·한도를 코드로 조회.
모델 ID 목록·alias 매핑·가용 범위는 시점과 배포처(Claude API, AWS, Vertex, Foundry)에 따라 다를 수 있습니다. 프로덕션 반영 전 반드시 공식 모델 문서에서 최신 ID와 deprecation 일정을 확인하세요.