# Proxy Anthropic Requests

[Anthropic](https://www.anthropic.com/) provides the native Messages API and an OpenAI-compatible API for accessing Claude models.

This guide shows how to integrate APISIX with Anthropic using the [`ai-proxy`](https://docs.api7.ai/hub/ai-proxy.md) plugin. With provider set to `anthropic`, you do not need to set a custom endpoint.

## Prerequisite(s)[​](#prerequisites "Direct link to Prerequisite(s)")

* Install [Docker](https://docs.docker.com/get-docker/).
* Install [cURL](https://curl.se/) to send requests to the services for validation.
* Follow the [Getting Started Tutorial](https://docs.api7.ai/apisix/getting-started.md) to start a new APISIX instance in Docker or on Kubernetes.

## Obtain an Anthropic API Key[​](#obtain-an-anthropic-api-key "Direct link to Obtain an Anthropic API Key")

Create an account and API key by following the [Anthropic API documentation](https://platform.claude.com/docs/en/api/overview). Save the key and a supported [model ID](https://platform.claude.com/docs/en/models/overview) to environment variables:

```
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # replace with your API key

export ANTHROPIC_MODEL=claude-sonnet-5-5
```

## Create a Route to Anthropic[​](#create-a-route-to-anthropic "Direct link to Create a Route to Anthropic")

This example accepts an OpenAI Chat Completions request on a custom path. APISIX identifies the format from the `messages` field and sends it to Anthropic's OpenAI-compatible endpoint. To accept the native Anthropic Messages format instead, configure a route URI ending in `/v1/messages`; see [Native Anthropic Messages API Pass-Through](https://docs.api7.ai/hub/ai-proxy.md#native-anthropic-messages-api-pass-through).

Create a route with the [`ai-proxy`](https://docs.api7.ai/hub/ai-proxy.md) plugin as such:

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @- <<EOF

{

  "id": "anthropic-chat",

  "uri": "/anything",

  "plugins": {

    "ai-proxy": {

      "provider": "anthropic",

      "auth": {

        "header": {

          "x-api-key": "$ANTHROPIC_API_KEY"

        }

      },

      "options": {

        "model": "$ANTHROPIC_MODEL"

      }

    }

  }

}

EOF
```

❶ Set the provider to `anthropic`.

❷ Attach the Anthropic API key using the `x-api-key` header.

❸ Set the Anthropic model saved in `ANTHROPIC_MODEL`.

adc.yaml

```
services:

  - name: Anthropic Service

    routes:

      - uris:

          - /anything

        name: anthropic-chat

        plugins:

          ai-proxy:

            provider: anthropic

            auth:

              header:

                x-api-key: "${ANTHROPIC_API_KEY}"

            options:

              model: "${ANTHROPIC_MODEL}"
```

❶ Set the provider to `anthropic`.

❷ Attach the Anthropic API key using the `x-api-key` header.

❸ Set the Anthropic model saved in `ANTHROPIC_MODEL`.

Preview the service change. These options compare only this example's service, so other gateway resources stay unchanged:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-chat
```

Review `diff.yaml` and confirm that it contains only the intended service and route changes. Then synchronize the reviewed configuration with the same scope:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-chat
```

## Verify[​](#verify "Direct link to Verify")

Send a request with the following prompt to the route. The request omits `model` because `ai-proxy` adds the model configured in the plugin options:

```
curl "http://127.0.0.1:9080/anything" -X POST \

  -H "Content-Type: application/json" \

  -d '{"messages": [{"role": "user", "content": "Hello"}]}'
```

You should receive an OpenAI Chat Completions response similar to the following. The generated text, identifiers, timestamp, and token counts are illustrative and vary between requests:

```
{

  "id": "msg_01HUQ8fAR1XvJ9PodefrZixW",

  "object": "chat.completion",

  "created": 1793350800,

  "model": "claude-sonnet-5-5",

  "choices": [

    {

      "index": 0,

      "finish_reason": "stop",

      "message": {

        "role": "assistant",

        "content": "Hello! How can I help you today?"

      }

    }

  ],

  "usage": {

    "prompt_tokens": 8,

    "completion_tokens": 12,

    "total_tokens": 20

  }

}
```

For this OpenAI-compatible response, `prompt_tokens` already includes cache usage. Do not add the separate cache fields when calculating total prompt usage.

## Proxy Native Anthropic Messages[​](#proxy-native-anthropic-messages "Direct link to Proxy Native Anthropic Messages")

When the client and Anthropic both use the Messages API, configure a route ending in `/v1/messages`. APISIX detects the path and forwards the native request without protocol conversion, preserving Anthropic-specific request and response fields.

Create a native Messages route:

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @- <<EOF

{

  "id": "anthropic-messages",

  "uri": "/v1/messages",

  "plugins": {

    "ai-proxy": {

      "provider": "anthropic",

      "auth": {

        "header": {

          "x-api-key": "$ANTHROPIC_API_KEY"

        }

      },

      "options": {

        "model": "$ANTHROPIC_MODEL"

      }

    }

  }

}

EOF
```

adc.yaml

```
services:

  - name: Anthropic Messages Service

    routes:

      - uris:

          - /v1/messages

        name: anthropic-messages

        plugins:

          ai-proxy:

            provider: anthropic

            auth:

              header:

                x-api-key: "${ANTHROPIC_API_KEY}"

            options:

              model: "${ANTHROPIC_MODEL}"
```

Preview the native Messages service separately so this example does not replace the Chat Completions service configured above:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-messages
```

Review `diff.yaml` and confirm that it contains only the native Messages service and route. Then synchronize the reviewed configuration with the same scope:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=anthropic-messages
```

Send a native Messages request:

```
curl "http://127.0.0.1:9080/v1/messages" -X POST \

  -H "Content-Type: application/json" \

  -H "anthropic-version: 2023-06-01" \

  -d '{

    "max_tokens": 128,

    "messages": [

      {

        "role": "user",

        "content": "Hello"

      }

    ]

  }'
```

You should receive a native Anthropic Messages response similar to the following. The generated text, identifiers, and token counts are illustrative and vary between requests:

```
{

  "id": "msg_01HUQ8fAR1XvJ9PodefrZixW",

  "type": "message",

  "role": "assistant",

  "model": "claude-sonnet-5-5",

  "content": [

    {

      "type": "text",

      "text": "Hello! How can I help you today?"

    }

  ],

  "stop_reason": "end_turn",

  "stop_sequence": null,

  "usage": {

    "input_tokens": 8,

    "output_tokens": 12

  }

}
```

APISIX preserves the native Anthropic `usage` object. For access logs, Prometheus metrics, and token-based rate limiting, the normalized prompt total includes input, cache-read, and cache-creation tokens. The separate cache fields remain available for custom accounting.

To verify streaming, send a request with `stream` set to `true`. The `-N` option disables curl response buffering so that each event is displayed as it arrives:

```
curl -N "http://127.0.0.1:9080/v1/messages" -X POST \

  -H "Content-Type: application/json" \

  -H "anthropic-version: 2023-06-01" \

  -d '{

    "max_tokens": 128,

    "stream": true,

    "messages": [

      {

        "role": "user",

        "content": "Hello"

      }

    ]

  }'
```

You should receive Anthropic SSE events ending with `message_stop`, similar to the following abbreviated response:

```
event: message_start

data: {"type":"message_start","message":{"type":"message","role":"assistant",...}}



event: content_block_delta

data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}



...



event: message_stop

data: {"type":"message_stop"}
```

## Next Steps[​](#next-steps "Direct link to Next Steps")

You have learned how to integrate APISIX with Anthropic. See the [Anthropic API documentation](https://platform.claude.com/docs/en/api/overview) and [Models](https://platform.claude.com/docs/en/models/overview) pages for more details.
