모든 Anthropic API 모델 이름을 검색했다면, 가장 빠른 답변은 이것입니다: Claude 표시 이름, 최신 모델 ID, 날짜 기반 스냅샷은 모두 유효해 보이지만 model 필드에는 정확한 API 식별자만 들어가야 합니다. Anthropic은 제품 페이지에서 사람이 읽을 수 있는 Claude 이름을, 재현 가능한 API 호출에는 날짜가 포함된 모델 ID를, 편리한 업그레이드를 위해 별칭을 사용합니다. 이 값들은 서로 연관되어 있지만, 상호 교체 가능하지는 않습니다.
실용적인 규칙은 간단합니다: 반복 가능한 동작이 필요하면 정확한 모델 ID를 사용하고, 의도적으로 Anthropic이 최신 스냅샷으로 이동시키길 원한다면 별칭을 사용하며, 공식 모델 목록을 먼저 확인하지 않고 마케팅 이름을 API 요청에 복사하지 마세요.
다음 단계가 명명 체계보다는 요청 형식이라면, 이 가이드를 Anthropic Messages API 문서와 함께 활용하세요. Claude 기반 코딩 워크플로우를 선택 중이라면, Claude Code 지원 모델이 더 나은 후속 자료입니다.
Anthropic API 모델 이름이란?
Anthropic API 모델 이름은 Messages API 요청의 model 매개변수에 전송되는 식별자입니다. 이는 Anthropic에 어떤 Claude 제품군과 스냅샷이 요청을 처리해야 하는지 알려줍니다.
다음 세 가지 형태는 혼동하기 쉽습니다:
| 값 유형 | 예시 | 최적 사용처 |
|---|---|---|
| 표시 이름 | Claude Sonnet | 문서, 제품 UI, 비기술적 독자와의 대화 |
| 최신 모델 ID | claude-sonnet-5 |
Anthropic의 최신 모델 페이지에 등록된 모델을 사용하는 새 통합 |
| 날짜 기반 모델 ID | claude-haiku-4-5-20251001 |
테스트, 규제 워크플로우, 평가, 재현 가능성이 필요한 프로덕션 배포 |
정확한 카탈로그는 시간이 지남에 따라 변경됩니다. 오래된 튜토리얼에서 복사한 목록을 하드코딩하지 말고 Anthropic의 최신 모델 페이지와 모델 폐기 페이지를 신뢰할 수 있는 정보원으로 취급하세요.
Claude 모델 이름과 Claude 모델 ID의 차이
Claude 모델 이름은 사람을 위해 최적화되어 있습니다. "Claude Sonnet"은 제품 계층을 전달하고, "Claude Haiku"는 더 빠르고 저렴한 계층을 암시합니다. API는 더 정밀한 값이 필요한데, 하나의 제품군이 여러 스냅샷, 리전별 가용성 규칙, 지원 종료 날짜를 가질 수 있기 때문입니다.
날짜 기반 ID에는 일반적으로 다음이 포함됩니다:
opus,sonnet,haiku와 같은 Claude 제품군.- 주요 모델 세대.
YYYYMMDD형식의 출시일.
예를 들어 claude-haiku-4-5-20251001은 2025년 10월 1일에 출시된 Haiku 4.5 스냅샷을 식별합니다. 날짜는 식별자의 일부이며 요청 타임스탬프가 아니므로 현재 날짜로 대체해서는 안 됩니다.
일부 모델 카탈로그는 더 짧은 제품군 수준 식별자도 제공합니다. 이는 날짜 기반 스냅샷을 직접 관리하지 않고 지원되는 모델을 사용하려는 경우 편리합니다. 단점은 공급자가 관리하는 포인터가 업데이트 후 동작을 변경할 수 있으므로, Anthropic의 최신 카탈로그에 표시된 정확한 ID의 의미를 반드시 확인해야 한다는 것입니다.
자주 접할 수 있는 일반적인 Claude 모델 ID
다음 API ID는 2026년 7월 24일 기준 Anthropic의 최신 모델 페이지에 활성 상태로 등록된 것입니다. 이 표는 특정 시점의 참고 자료이지 영구적인 레지스트리가 아닙니다. 새로운 배포에서 ID를 사용하기 전에 Anthropic의 문서를 확인하세요.
| Claude 제품군 | 최신 API ID | 일반적인 역할 |
|---|---|---|
| Claude Opus 4.8 | claude-opus-4-8 |
복잡한 추론 및 고위험 분석 |
| Claude Sonnet 5 | claude-sonnet-5 |
범용 프로덕션 워크로드 |
| Claude Haiku 4.5 | claude-haiku-4-5-20251001 |
빠른 분류, 추출, 짧은 응답 |
| Claude Opus 4.7 | claude-opus-4-7 |
아직 4.8로 전환하지 않은 최근 세대 Opus 통합 |
| Claude Sonnet 4.6 | claude-sonnet-4-6 |
아직 Sonnet 5로 전환하지 않은 최근 세대 Sonnet 통합 |
이는 식별자일 뿐이며, 모든 Anthropic 계정에서 모델을 사용할 수 있다는 보장은 아닙니다. 현재 등록된 ID라도 계정 권한, 리전, 할당량 또는 이후 라이프사이클 변경으로 인해 실패할 수 있습니다. 날짜 기반 ID는 지원되는 동안 재현 가능하지만, 결국에는 폐기됩니다.
Opus, Sonnet, Haiku 선택 방법
가장 긴 이름이 아니라 워크로드에 따라 선택하세요:
- Opus: 어려운 추론, 장문 합성, 미묘한 도구 결정이 더 높은 지연 시간이나 비용을 정당화할 때 사용하세요.
- Sonnet: 대부분의 프로덕션 어시스턴트, 코딩 워크플로우, 구조화된 생성을 위해 여기서 시작하세요. 일반적으로 실용적인 품질 대 지연 시간의 기준점입니다.
- Haiku: 대량 라우팅, 추출, 검열, 짧은 재작성 및 최대 추론 깊이보다 응답 시간이 더 중요한 기타 작업에 사용하세요.
제품군을 전환하기 전에 대표적인 프롬프트에 대해 소규모 평가를 실행하세요. 잘못된 입력, 긴 컨텍스트, 도구 호출, JSON 출력, 요청 실패 시 애플리케이션이 사용하는 폴백 동작을 포함하세요. 드롭인 교체처럼 보이는 모델 이름이라도 도구 호출 형식이나 에지 케이스 동작이 변경될 수 있습니다.
Messages API 요청에서 모델 ID 사용하기
model 값은 JSON 본문에 속합니다. 이는 API 버전 헤더 및 Claude 웹 앱에 표시되는 모델과 별개입니다.
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-5",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "프로덕션에서 API 모델 ID를 고정해야 하는 이유를 설명해주세요."
}
]
}'
anthropic-version 헤더는 API 계약을 설명합니다. 이는 Claude 모델을 선택하지 않습니다. 클라이언트 라이브러리 업그레이드가 모델 라우팅을 조용히 변경하지 않도록 이 두 설정을 구성에서 독립적으로 유지하세요.
SDK 사용 시 클라이언트의 메시지 생성 메서드를 통해 동일한 식별자를 설정하고 환경별 구성 값으로 유지하세요. 브라우저 번들에 API 키나 모델 ID를 넣지 마세요. 서버 측 라우팅이 보안 및 테스트에 더 용이합니다.
API 모델 ID가 작동을 멈추는 이유
invalid_request_error 또는 “모델을 찾을 수 없음” 응답은 일반적으로 다음 범주 중 하나에 속합니다:
표시 이름이 ID 대신 사용된 경우
Claude Sonnet은 유용한 레이블이지만 신뢰할 수 있는 요청 값은 아닙니다. 공급자 문서에 나열된 ID 또는 별칭으로 교체하세요.
스냅샷이 폐기된 경우
날짜 기반 ID는 공급자가 지원하는 동안에만 재현 가능합니다. 폐기 일정을 모니터링하고, 마이그레이션 기한을 설정하며, 지원 종료일 이전에 교체 모델을 테스트하세요.
계정에서 모델에 액세스할 수 없는 경우
유효한 식별자라도 계정 권한, 리전, 할당량 또는 조직 정책으로 인해 사용하지 못할 수 있습니다. 프롬프트를 변경하는 대신 응답 본문과 계정 구성을 확인하세요.
라우터가 공급자별 이름을 기대하는 경우
게이트웨이와 OpenAI 호환 API는 모델 이름을 다르게 정규화할 수 있습니다. Anthropic은 현재 claude-sonnet-5를 문서화하지만, 다른 공급자는 네임스페이스 값이나 공급자 소유 별칭을 노출할 수 있습니다. 게이트웨이의 모델 카탈로그를 사용하고 Claude ID가 모든 엔드포인트에서 이식 가능하다고 가정하지 마세요.
호환 엔드포인트를 통한 Claude 스타일 워크플로우 사용
애플리케이션이 이미 OpenAI 클라이언트 형태를 사용하고 있다면, 호환성 계층이 마이그레이션 작업을 줄일 수 있습니다. Novita LLM API는 친숙한 chat-completions 요청 형태를 통해 지원되는 오픈소스 모델을 라우팅하는 OpenAI 호환 엔드포인트를 제공합니다.
그렇다고 모든 Claude 모델 ID가 자동으로 사용 가능한 것은 아닙니다. 공급자 라우팅을 명시적으로 유지하세요:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/v3/openai",
)
response = client.chat.completions.create(
model="moonshotai/kimi-k2.5",
messages=[
{"role": "user", "content": "이 지원 티켓을 세 가지 요점으로 요약해주세요."}
],
)
print(response.choices[0].message.content)
중요한 디자인 패턴은 단일 전역 문자열이 아닌 공급자/모델 맵입니다:
MODELS = {
"anthropic": "claude-sonnet-5",
"novita": "moonshotai/kimi-k2.5",
}
이를 통해 비즈니스 로직을 다시 작성하지 않고도 Claude 모델을 오픈소스 대안과 평가할 수 있습니다. 전환하기 전에 표시 이름이나 벤치마크 헤드라인뿐만 아니라 구조화된 출력, 도구 호출, 컨텍스트 처리, 지연 시간, 실패 모드를 비교하세요.
에이전트 백엔드 및 샌드박스의 모델 ID
에이전트는 일반적으로 모델을 여러 번 호출합니다: 계획 수립, 도구 선택, 코드 수정, 최종 응답 등. 모델 식별자는 사용자 제어 도구 인수가 아닌 백엔드 구성에 두세요. 각 실행과 함께 선택된 공급자와 모델 ID를 로깅하여 나중에 평가를 재현할 수 있도록 하세요.
에이전트가 생성된 코드를 실행할 때, 모델 라우팅을 실행 환경과 분리된 상태로 유지하세요. 관리형 Agent Sandbox는 파일, 패키지, 명령을 격리할 수 있으며, LLM API 구성은 에이전트 서비스에 남아 있습니다. 이 분리를 통해 샌드박스 이미지를 변경하지 않고 모델 별칭을 변경하거나 고정된 스냅샷을 테스트할 수 있습니다.
프로덕션 에이전트의 경우 세 가지 안전장치를 추가하세요:
- 시작 시 작은 인증 요청 또는 공급자 카탈로그 확인을 통해 구성된 모델의 유효성을 검증하세요.
- 테스트된 폴백 ID를 유지하고 폴백 활성화를 텔레메트리에서 확인할 수 있게 하세요.
- 모델 ID, API 버전, 프롬프트 버전, 도구 스키마를 평가 결과와 함께 저장하세요.
FAQ
API에 올바른 Claude 모델 이름은 무엇인가요?
claude-sonnet-5 또는 날짜 기반 claude-haiku-4-5-20251001과 같이 Anthropic의 최신 문서에 나열된 정확한 모델 ID를 사용하세요. "Claude Sonnet"과 같은 표시 이름을 단독으로 사용하지 마세요.
날짜 기반 Claude 모델 ID가 별칭보다 더 나은가요?
어느 쪽이 항상 더 낫다고 할 수는 없습니다. 날짜 기반 ID는 재현 가능성과 통제된 롤아웃에 선호됩니다. 별칭은 유지 관리되는 제품군 포인터를 원하고 공급자 업데이트에 대한 회귀 테스트가 있는 경우 선호됩니다.
OpenAI 호환 API에서 Anthropic 모델 ID를 사용할 수 있나요?
해당 엔드포인트가 ID를 명시적으로 지원하고 문서화하는 경우에만 가능합니다. OpenAI 호환은 요청 인터페이스를 설명할 뿐, 동일한 모델 카탈로그를 보장하지는 않습니다. 엔드포인트의 지원 모델을 확인하고 정확한 라우팅 이름을 사용하세요.
모델 폐기로 인해 앱이 중단되는 것을 방지하려면 어떻게 해야 하나요?
테스트된 ID를 고정하고, Anthropic의 폐기 공지를 모니터링하며, 지원 종료일 이전에 교체 모델을 테스트하고, 비즈니스 로직 변경 없이 모델 값을 변경할 수 있도록 구성을 유지하세요.
