Anthropic Messages Gateway
Use the Anthropic Messages gateway when a client expects Anthropic's Messages API shape but you want requests to run through Hatz.
For endpoint schemas, parameters, and request examples, use the Anthropic Messages API docs.
Not to be confused with the AI Gateway. This article covers the Anthropic-compatible endpoint. The AI Gateway, in Settings > AI Gateway, decides how requests to it are billed: in Hatz credits by default, or in USD once your MSP has activated the AI Gateway and your tenant has opted in. See AI Gateway: pay for API usage in USD in the MSP / Admins collection.
Base URL
For Anthropic SDK clients and Claude Desktop gateway-style configuration, use:
https://ai.hatz.ai/v1/anthropic
The SDK appends /v1/messages, so Hatz accepts both paths:
/v1/anthropic/messages/v1/anthropic/v1/messages
The token counting paths are:
/v1/anthropic/messages/count_tokens/v1/anthropic/v1/messages/count_tokens
Authentication
Use a Hatz API key as the gateway credential.
Authorization: Bearer <Hatz API key>
or:
X-API-Key: <Hatz API key>
Automatic model discovery
Claude Desktop and Claude Code fill in their own model list. With the gateway base URL configured, the client requests https://ai.hatz.ai/v1/anthropic/v1/models with your Hatz API key and populates its model picker from the reply. You do not need to type model IDs.
The reply lists only models that your own Hatz account can actually invoke, so a model you pick from that list is one your key can use immediately. Models your account cannot reach are left out rather than shown and rejected later. On Hatz credits, the list contains Claude models. If your organization uses AI Gateway USD billing, it can also contain models from other providers, and only models available for USD billing are listed.
Both spellings answer the same list, and neither redirects:
/v1/anthropic/v1/models/v1/anthropic/models
Manual fallback. If your client has model discovery turned off, or its list comes back empty, choosing a model by hand is fully supported and works the same way. Use a Hatz model ID from the next section.
Model IDs and aliases
If you are naming a model yourself, use a Hatz model ID. You can list them with /v1/chat/models, such as:
anthropic.claude-haiku-4-5anthropic.claude-sonnet-4-5anthropic.claude-opus-4-7moonshot.kimi-k2-thinking
If your organization uses AI Gateway USD billing, take model IDs from /v1/anthropic/v1/models instead. /v1/chat/models also lists models that aren't available for USD billing.
For clients that send Anthropic family names, Hatz also accepts these aliases:
opus: current enabled Claude Opus family model.sonnet: current enabled Claude Sonnet family model.haiku: current enabled Claude Haiku family model.
Users can turn on Custom Anthropic Gateway Model Mapping in Settings > AI Preferences to map opus, sonnet, and haiku to selected Hatz models. This setting only affects Anthropic-compatible gateway requests. It does not change the normal Hatz model picker.
Python example
import anthropicimport osclient = anthropic.Anthropic( base_url="https://ai.hatz.ai/v1/anthropic", api_key=os.environ["HATZ_API_KEY"],)message = client.messages.create( model="anthropic.claude-haiku-4-5", max_tokens=128, messages=[{"role": "user", "content": "Reply with one short sentence."}],)print(message.content[0].text)
Claude Desktop gateway setup
In Claude Desktop's third-party inference settings, choose the Anthropic-compatible gateway option and configure:
Gateway base URL:
https://ai.hatz.ai/v1/anthropicGateway API key: your Hatz API key
Gateway auth scheme: Bearer
Model list: leave this to the client. It discovers the models your key can invoke on its own. If discovery is turned off, enter Hatz model IDs, or aliases such as
opus,sonnet, andhaiku
Only list models that the user's Hatz account can access. If an alias maps to a rate-limited model, requests fail with a rate-limit response instead of falling back to a different allowed model.
Supported behavior
Text messages.
Anthropic-style streaming events.
Client-managed tool calls and tool results.
Token counting for preflight checks.
Anthropic-style web search response shapes through Hatz-hosted Firecrawl search when enabled.
Provider-specific Anthropic features are supported only when Hatz documents them for this gateway and they are enabled for the selected model and account.
With AI Gateway USD billing, a few extra limits apply:
Web search works only with Claude models, using Hatz's built-in search (the
web_search_20250305tool type). Other web search tool types are refused.Prompt caching (
cache_control) works with Claude models and some other models. On a model that doesn't support it for USD billing, a request that includescache_controlis refused. Remove it, or choose a Claude model.A 1-hour cache lifetime is applied as 5 minutes.
A maximum input size applies, which can be smaller than the model's full context window. Longer requests are refused.
Budgets are checked against an estimate of the most a request can cost, so set
max_tokensno higher than you need.
Usage and billing
Generation requests are billed in Hatz credits, or in USD when your MSP has activated the AI Gateway and your tenant has opted in. Token counting requests are preflight checks and are not billed by themselves.
Troubleshooting
If Claude Desktop changes
opusinto a full Claude model ID, add that full model ID to the model list or use custom alias mapping in Hatz AI Preferences.If the response says the model was not found, pick a model from the client's discovered list, or query
/v1/chat/modelsand use a model ID from that list. If your organization uses AI Gateway USD billing, use/v1/anthropic/v1/modelsinstead.If the client's model list is empty or fails to load, your key may not be able to invoke any Claude model on its current plan; name a model by hand to confirm, and ask an administrator which models your account can use.
If the response is rate limited, choose a model that is available under the user's package, tenant, and role limits.
If web search returns a message that search is not enabled, ask an administrator whether the environment has Anthropic gateway web search enabled.
If the error message mentions LLM Gateway (the AI Gateway's name in error messages), such as
LLM Gateway is not enabled for your organizationor a budget that has been reached, see AI Gateway: pay for API usage in USD in the MSP / Admins collection.If the response says the request uses a feature that is not available for LLM gateway billing, remove web search tools or
cache_controlfrom the request, or choose a Claude model.If support needs to investigate, include the Hatz request ID, the requested model, whether streaming was enabled, and the external client being used.
