Anthropic-Style Messages API

Anthropic-style proxy routes fit applications that already send Anthropic Messages requests and need AISIX to manage gateway-side authentication, model aliases, routing, and policy.

The client keeps the Anthropic-style request and response format. AISIX becomes the endpoint the client calls, and the upstream provider can be Anthropic or another supported provider family.

This guide describes the proxy API behavior. For a runnable SDK setup, see Anthropic SDK Quickstart.

What the Client Sends

The client sends three AISIX-owned values:

• The base URL is the AISIX proxy API root, for example http://127.0.0.1:3000.
• The API key is an AISIX caller API key.
• The model value is an AISIX model alias, such as claude-prod.

The request body keeps the Anthropic Messages format, including messages, max_tokens, tools, and stream. The caller uses the AISIX caller API key, not the upstream Anthropic provider key.

Anthropic SDKs send the caller API key as x-api-key. AISIX also accepts bearer tokens for direct HTTP clients.

Messages Request

Send a Messages request through AISIX:

curl -sS -X POST "http://127.0.0.1:3000/v1/messages" \
  -H "x-api-key: YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-prod",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Say hello from AISIX."}
    ]
  }'

A successful response uses the Anthropic Messages format. The model value in the request is the AISIX model alias, not necessarily the upstream provider model ID.

Choose an Upstream Path

Like other AISIX proxy APIs, /v1/messages lets the client request format stay stable while the upstream provider changes. For Anthropic-style requests, the upstream choice matters because Anthropic-backed models preserve more Anthropic-specific behavior than translated upstreams.

Upstream path	What it gives you	Use it when
Anthropic-backed model	Native Anthropic request and response behavior, with AISIX handling the caller key, provider key, and model alias.	The application depends on Anthropic-specific behavior such as thinking blocks, image blocks, cache control, or exact tool-use semantics.
Translated upstream	An Anthropic-style client edge with a non-Anthropic upstream behind AISIX.	The application needs to keep an Anthropic-style client while AISIX routes traffic to another supported provider family.

The translated path supports common text and tool-calling flows, but it does not match native Anthropic behavior in every detail. Prefer an Anthropic-backed model when the application depends on Anthropic-specific content blocks or provider-specific request fields.

Route Behavior

/v1/messages can use single-target and multi-target model aliases. Non-streaming requests can fail over to the next target on retryable upstream failures.

Streaming requests use the first selected target and do not fail over after the stream starts. For general streaming behavior, see Streaming.

POST /v1/messages/count_tokens uses the same AISIX caller API key and accepts the Anthropic token-counting request format. This route only uses Anthropic-backed targets. If no Anthropic-backed target is available, AISIX rejects the request.

Handle Errors

Messages routes return errors in an Anthropic-style envelope. The error type follows Anthropic SDK-compatible status mappings, so Anthropic clients can parse gateway-generated errors with the same error-handling path they use for provider errors.

Native Anthropic upstream errors can include request_id. AISIX does not add that field to gateway-generated Anthropic-style errors.

For the full error and header reference, see Headers and Error Codes. For provider-defined error types, see Anthropic's Errors documentation.

Next Steps

You have now seen how Anthropic-style clients call AISIX. Continue with Streaming, Tool Calling, or Proxy Errors and Retries when your application depends on those behaviors.