Proxy Anthropic Requests
Anthropic 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 plugin. With provider set to anthropic, you do not need to set a custom endpoint.
Prerequisite(s)
- Install Docker.
- Install cURL to send requests to the services for validation.
- Follow the Getting Started Tutorial to start a new APISIX instance in Docker or on Kubernetes.
Obtain an Anthropic API Key
Create an account and API key by following the Anthropic API documentation. Save the key and a supported model ID 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
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.
Create a route with the ai-proxy 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.
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
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
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
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
You have learned how to integrate APISIX with Anthropic. See the Anthropic API documentation and Models pages for more details.