Skip to main content
API7.ai Logo

Anthropic

Anthropic develops the Claude family of models and provides the native Messages API for accessing them. AISIX lets applications use either the native Messages format or the gateway's OpenAI-compatible API while managing the Anthropic credential, caller access, rate limits, and usage accounting.

This guide connects AISIX directly to Anthropic. To reach Claude through AWS instead, use AWS Bedrock.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • An Anthropic API key from the Anthropic Console.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the Anthropic-backed route.

AISIX connects to Anthropic through the native anthropic adapter and authenticates upstream requests with Anthropic's x-api-key header.

Create a Provider Key​

Create the provider key that stores the Anthropic credential and allow it into the environment:

# Replace with your value
export ANTHROPIC_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "anthropic-prod",
    "provider": "anthropic",
    "api_key": "'"${ANTHROPIC_API_KEY}"'",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

❶ provider is anthropic. The AISIX Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys. AISIX sends the credential as the x-api-key header and adds anthropic-version: 2023-06-01 on outbound calls.

❷ api_key stores the Anthropic API key. It follows the credential-handling behavior in Provider Keys.

You can omit api_base for Anthropic; it falls back to the Anthropic default endpoint. The response returns the provider key ID, captured above as PROVIDER_KEY_ID.

Create a Model​

Claude model IDs from the 4.6 generation onward are pinned snapshots, not evergreen pointers. Check the Anthropic models reference for the current IDs.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "claude-sonnet-prod",
    "model_name": "claude-sonnet-5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

❶ display_name is the alias callers send in model.

❷ model_name is the Claude model ID, for example claude-sonnet-5, claude-opus-4-8, or claude-haiku-4-5.

❸ provider_key_id attaches the alias to the Anthropic provider key.

Create a Caller API Key​

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the create response:

export AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "claude-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

The allowed_models value references the model by its ID, captured above as MODEL_ID. Store the plaintext key securely; it is not retrievable later.

Callers authenticate to AISIX with a caller API key in the Authorization: Bearer header. AISIX supplies the Anthropic x-api-key and anthropic-version headers to the upstream; clients do not send them.

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export ANTHROPIC_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "anthropic-prod"
    provider: "anthropic"
    adapter: "anthropic"
    api_key: ${ANTHROPIC_API_KEY}
    api_base: "https://api.anthropic.com"

models:
  - display_name: "claude-sonnet-prod"
    provider: "anthropic"
    model_name: "claude-sonnet-5"
    provider_key: "anthropic-prod"

api_keys:
  - display_name: "claude-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "claude-sonnet-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a native Messages request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/messages" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-prod",
    "max_tokens": 64,
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Claude."
      }
    ]
  }'

The gateway returns an Anthropic Messages response that echoes the caller-facing alias claude-sonnet-prod. If the request fails with an upstream authentication error, check the provider key api_key.

The same alias also works on /v1/chat/completions for OpenAI-shaped clients. This translation drops non-text content blocks, so call /v1/messages directly for image or document inputs.

Clean Up​

When you no longer need the example resources, delete the claude-caller caller API key, the claude-sonnet-prod model, and the anthropic-prod provider key from the dashboard, in that order.

Next Steps​

You have now connected AISIX to Anthropic and verified the model alias. Continue with these guides:

  • Anthropic SDK: call this alias from an Anthropic SDK at /v1/messages.
  • AWS Bedrock: configure a Bedrock-hosted Claude model instead.
  • Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
  • Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.