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.

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>

Model IDs and aliases

The safest setup is to use Hatz model IDs returned by /v1/chat/models, such as:

anthropic.claude-haiku-4-5
anthropic.claude-sonnet-4-5
anthropic.claude-opus-4-7
moonshot.kimi-k2-thinking

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 Workspace > 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 anthropic
import 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: 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.

  • Prompt cache-control pass-through where the selected provider supports it.

  • Anthropic-style web search response shapes through Hatz-hosted Firecrawl search when enabled.

Usage and credits

Generation requests are counted as Hatz usage. Token counting requests are preflight checks and do not create usage records 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, query /v1/chat/models and use a model ID from that list.

  • 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 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?