Anthropic SDK Quickstart

In this guide, you will point an Anthropic-style SDK client at AISIX AI Gateway. This flow fits applications that already use the Anthropic Messages format and need to keep that client code mostly unchanged.

The setup adds an Anthropic-backed model alias to the local gateway, creates a caller API key for that alias, and calls POST /v1/messages through the Anthropic Python SDK.

This guide has more gateway setup than the OpenAI SDK quickstart because the main quickstart already creates the OpenAI provider key, model alias, and caller API key. Anthropic uses the same gateway resource pattern, but a different client API shape, so this quickstart creates the Anthropic equivalents before running the SDK example.

Prerequisites

• Complete the Quickstart.
• Prepare an Anthropic API key.
• Install Python 3.8 or later.
• Install curl and jq to create and verify the example alias.

Request Flow

The main quickstart creates an OpenAI-backed alias named gpt-4o-mini. This quickstart adds claude-demo, an Anthropic-backed alias, so an Anthropic SDK client can call AISIX through /v1/messages.

Keep the Anthropic SDK client, but send requests through the gateway instead of calling Anthropic directly:

The application sends the caller API key sk-anthropic-caller, the AISIX model alias claude-demo, and the gateway base URL http://127.0.0.1:3000.

AISIX resolves claude-demo to the upstream Anthropic model and injects the stored provider credential on the upstream side.

Configure the Gateway

Create an Anthropic provider key, add a claude-demo model alias, and create a caller API key that can use that alias.

Set Environment Variables

Export the values used by the admin commands:

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export AISIX_API_KEY="sk-anthropic-caller"
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"   # Replace with your Anthropic API key
export ANTHROPIC_MODEL="claude-sonnet-4-6"          # Upstream model ID AISIX sends to Anthropic
export AISIX_ANTHROPIC_ALIAS="claude-demo"          # Client-facing model name your application sends to AISIX

Create an Anthropic Provider Key

Create a provider key that stores the upstream Anthropic credential:

ANTHROPIC_PROVIDER_KEY_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "anthropic-upstream",
    "provider": "anthropic",
    "adapter": "anthropic",
    "secret": "'"${ANTHROPIC_API_KEY}"'",
    "api_base": "https://api.anthropic.com"
  }')

printf '%s\n' "${ANTHROPIC_PROVIDER_KEY_RESPONSE}" | jq .
ANTHROPIC_PROVIDER_KEY_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_PROVIDER_KEY_RESPONSE}")

AISIX appends /v1/messages to api_base, so use the bare host https://api.anthropic.com.

Create an Anthropic-Backed Model Alias

Create the client-facing model alias:

ANTHROPIC_MODEL_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "'"${AISIX_ANTHROPIC_ALIAS}"'",
    "provider": "anthropic",
    "model_name": "'"${ANTHROPIC_MODEL}"'",
    "provider_key_id": "'"${ANTHROPIC_PROVIDER_KEY_ID}"'"
  }')

printf '%s\n' "${ANTHROPIC_MODEL_RESPONSE}" | jq .
ANTHROPIC_MODEL_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_MODEL_RESPONSE}")

The client sends claude-demo to AISIX. The upstream provider receives claude-sonnet-4-6.

Create an AISIX API Key

Create a caller API key that can access claude-demo:

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

ANTHROPIC_APIKEY_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": ["'"${AISIX_ANTHROPIC_ALIAS}"'"]
  }')

printf '%s\n' "${ANTHROPIC_APIKEY_RESPONSE}" | jq .
ANTHROPIC_APIKEY_ID=$(jq -r '.id // empty' <<< "${ANTHROPIC_APIKEY_RESPONSE}")

Verify the Alias Is Visible

List the models visible to the caller API key:

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  | jq -r '.data[].id'

The output should include claude-demo.

Run the SDK Example

Install the Anthropic SDK, point it at AISIX, and send one Anthropic-style request through the gateway.

Install the Anthropic SDK

Create and activate a small Python environment:

python3 -m venv .venv
. .venv/bin/activate

Install the Anthropic SDK inside the virtual environment:

python -m pip install anthropic

Create a Client Example

Use your Anthropic-compatible client with the gateway base URL and your caller API key:

anthropic-sdk-example.py

import os

from anthropic import Anthropic

client = Anthropic(
  api_key=os.environ["AISIX_API_KEY"],
  base_url=os.environ["AISIX_BASE_URL"],
)

message = client.messages.create(
  model=os.environ.get("AISIX_MODEL", "claude-demo"),
  max_tokens=128,
  messages=[{"role": "user", "content": "Say hello from AISIX."}],
)

print(message.content[0].text)

Set the gateway-facing SDK values:

export AISIX_API_KEY="sk-anthropic-caller"
export AISIX_MODEL="claude-demo"
export AISIX_BASE_URL="http://127.0.0.1:3000"

Run the example:

python anthropic-sdk-example.py

You should see a short assistant response. The exact text depends on the upstream model.

Verify the SDK Response

When the gateway can resolve claude-demo and the upstream is reachable, the client receives an Anthropic-style message response from AISIX.

At the client edge, the SDK sends the request to POST /v1/messages; model is the AISIX model alias, and messages plus max_tokens follow the Anthropic Messages format. AISIX authenticates the caller API key, checks allowed_models, resolves the alias, and injects the upstream Anthropic provider key.

Compatibility Boundaries

POST /v1/messages can resolve both Anthropic-backed and non-Anthropic-backed model aliases. Anthropic-backed aliases preserve Anthropic-specific request and response behavior most directly.

Non-Anthropic translation is useful when you need a stable Anthropic-style client edge, but it is not feature-identical to native Anthropic behavior. If your application depends on tool-result round trips, thinking blocks, image blocks, or other Anthropic-specific content blocks, prefer an Anthropic-backed alias and validate the exact flow.

For the full endpoint behavior, see Anthropic Messages.

If the SDK Request Fails

First check that the SDK uses the caller API key, gateway base URL, and AISIX model alias from this quickstart.

If AISIX returns 404, the requested model alias is not configured. If AISIX returns 403, the caller API key exists but is not allowed to use that alias.

Optional Cleanup

If you created these resources only for this quickstart, delete the caller API key first. If you plan to keep using the Anthropic SDK through AISIX, leave them in place.

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/apikeys/${ANTHROPIC_APIKEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

Then delete the model alias:

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/models/${ANTHROPIC_MODEL_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

Then delete the provider key that stored the upstream Anthropic credential:

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/provider_keys/${ANTHROPIC_PROVIDER_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

To remove every local quickstart resource, run docker compose down -v from the quickstart working directory.

Next Steps

You have now called AISIX from an Anthropic SDK client. From here, review /v1/messages behavior and Streaming across endpoint families. For provider support, see Provider Compatibility.