Anthropic Messages Compatibility

Use this page when a client expects Anthropic Messages API wire format.

Which endpoint should I use?

The Anthropic SDK appends /v1/messages to its base URL. Configure SDK clients with:

https://ai.hatz.ai/v1/anthropic

The API also accepts /v1/anthropic/v1/messages and /v1/anthropic/v1/messages/count_tokens for that SDK path.

Direct HTTP calls can use:

https://ai.hatz.ai/v1/anthropic/messages

Model IDs

Use Hatz model IDs from your tenant's model list. For Claude Desktop gateway compatibility, the route also accepts the shorthand aliases sonnet, opus, and haiku and resolves them to Hatz model IDs before execution.

curl 'https://ai.hatz.ai/v1/chat/models' \
  -H "X-API-Key: $HATZ_API_KEY"

Examples of valid Hatz IDs include anthropic.claude-haiku-4-5 and moonshot.kimi-k2-thinking when enabled for your tenant.

By default, shorthand aliases resolve to the current enabled Anthropic model in the matching family. Users can enable Custom Anthropic Gateway Model Mapping in Hatz AI Preferences to override each alias to another enabled Hatz model. Turning the setting off preserves saved mappings but makes the gateway use the default family models again.

Native Claude-style IDs such as claude-sonnet-*, claude-opus-*, and claude-haiku-* are accepted for Claude Desktop compatibility and resolve through the matching family alias. Use a Hatz model ID from /v1/chat/models when you need to pin an exact enabled model.

Authentication

This endpoint accepts both authentication methods:

• Authorization: Bearer <your-api-key>
• X-API-Key: <your-api-key>

Bearer authentication is supported on the Anthropic- and OpenAI-compatible endpoints only — the rest of the Hatz API (including /chat/models above) requires X-API-Key. See the main authentication docs for details.

Do not send API keys in query strings, request bodies, Basic auth, screenshots, or support messages.

Anthropic SDK Example

import anthropic
import os

client = 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)

curl Example

curl 'https://ai.hatz.ai/v1/anthropic/messages' \
  -H 'Authorization: Bearer '"$HATZ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "anthropic.claude-haiku-4-5",
    "max_tokens": 128,
    "messages": [
      {
        "role": "user",
        "content": "Write a 2 sentence summary of SOC 2."
      }
    ]
  }'

Streaming

Set stream: true to receive Anthropic-style named SSE events:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop

Provider errors are returned as event: error with an Anthropic-compatible error payload.

Tool Calling

Request tools use Anthropic tools and tool_choice shapes. The server maps them into the runtime provider's supported tool format, and the client remains responsible for executing tools and sending tool_result blocks in a follow-up request.

web_search_20250305 is accepted for Claude Desktop compatibility. When requested, the gateway uses Hatz-hosted Firecrawl search, injects usable search results into model context, and prefixes the response with Anthropic-style web search result blocks. The provider-facing request does not receive Anthropic's built-in search tool directly.

If search is unavailable or returns no usable results, the gateway still returns an Anthropic-style response with server_tool_use and web_search_tool_result blocks that describe the unavailable search result.

Token Counting

/v1/anthropic/messages/count_tokens is intended for client-side limit checks. Hatz may use a fast local estimate with a safety multiplier, or an exact provider count for multimodal, structured, tool-heavy, or near-limit prompts. Usage accounting is recorded from the final model response, not from this preflight endpoint.

Troubleshooting

If a request fails:

• Confirm the client base URL is https://ai.hatz.ai/v1/anthropic.
• Confirm the API key is sent as Authorization: Bearer <your-api-key> or X-API-Key.
• Query /v1/chat/models with X-API-Key and use a model ID or supported alias enabled for your tenant.
• Use /v1/chat/completions instead if you need Hatz-native agents, server-side tools, recursive tool calling, or model: "auto".
• Treat /messages/count_tokens as a preflight limit check, not final billing truth.
• Include the X-Request-ID response header, timestamp, status code, sanitized error body, SDK/client version, model ID or alias, and whether streaming or tools were involved when contacting Support.

For status-code triage and a full support evidence packet, see API Troubleshooting.