Skip to main content

Anthropic Messages Gateway

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/anthropic

  • Gateway 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, and haiku

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_20250305 tool 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 includes cache_control is 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_tokens no 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 opus into 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/models and use a model ID from that list. If your organization uses AI Gateway USD billing, use /v1/anthropic/v1/models instead.

  • 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 organization or 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_control from 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.

Did this answer your question?