Principle:Anthropics Anthropic sdk python Model Identifier Mapping
| Knowledge Sources | |
|---|---|
| Domains | Cloud_Deployment, LLM, Infrastructure |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Each cloud provider uses a different model naming convention for Claude models. The Anthropic Python SDK provides a unified ModelParam type that accepts both well-known Anthropic model identifiers and arbitrary strings, allowing users to specify provider-specific model names. The provider clients then internally rewrite API request URLs to route to the correct model endpoint, abstracting away the differences in how each cloud provider addresses models.
Provider-Specific Model Naming Conventions
Anthropic Direct API
The canonical model identifiers used by the direct Anthropic API follow the pattern claude-{family}-{version}, optionally with date suffixes:
claude-sonnet-4-20250514claude-opus-4-20250514claude-haiku-4-5-20251001claude-sonnet-4-5-20250929
The SDK enumerates known model IDs as a Literal union in ModelParam, while also accepting any str to allow forward compatibility with new models.
AWS Bedrock
Bedrock uses either AWS model ARNs or cross-region inference profile IDs:
- Cross-region format:
us.anthropic.claude-sonnet-4-20250514-v1:0 - ARN format:
arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-sonnet-4-20250514-v1:0
The model identifier is extracted from the request body and embedded into the URL path (/model/{model}/invoke or /model/{model}/invoke-with-response-stream) by the Bedrock client's _prepare_options() method. The model string is URL-encoded with : preserved as a safe character.
Google Cloud Vertex AI
Vertex AI uses a publisher-prefixed format with an @ separator for the date:
claude-sonnet-4@20250514claude-opus-4@20250514
The model identifier is extracted from the request body and placed into the Vertex AI URL path: /projects/{project_id}/locations/{region}/publishers/anthropic/models/{model}:{specifier}, where {specifier} is either rawPredict or streamRawPredict.
Azure AI Foundry
Foundry uses the standard Anthropic model names (the same names as the direct API):
claude-sonnet-4-20250514claude-opus-4-20250514
The Foundry client inherits URL handling from the base Anthropic client and does not perform model-based URL rewriting, since Azure routes requests to the correct model based on the model field in the JSON body.
URL Path Rewriting via _prepare_options()
The core mechanism for model identifier mapping is the _prepare_options() method, which each provider client overrides. This method intercepts the FinalRequestOptions object before the HTTP request is dispatched and transforms the URL path and request body as needed:
- The
modelfield is popped from the JSON body. - A provider-specific URL is constructed using the model identifier.
- Provider-specific version headers or body fields (e.g.,
anthropic_version) are injected.
This approach keeps the model identifier mapping logic isolated from the shared Messages resource class, which always posts to the generic /v1/messages path. The provider client transparently rewrites this path before the request reaches the network.
The ModelParam Type
The ModelParam type is defined as a union of known Literal model strings and a catch-all str:
ModelParam: TypeAlias = Union[
Literal[
"claude-opus-4-6",
"claude-opus-4-5-20251101",
"claude-opus-4-5",
"claude-sonnet-4-20250514",
"claude-sonnet-4-0",
# ... additional known models
],
str,
]
This design provides IDE autocompletion and type checking for known models while allowing any provider-specific model string (such as Bedrock ARNs or Vertex publisher identifiers) to be used without type errors.