Skip to main content
API7.ai Logo

Anthropic SDK

Point the Anthropic Python SDK at AISIX AI Gateway to keep the Anthropic Messages request format while the gateway manages caller authentication, model aliases, routing, and policy.

The SDK needs only a gateway base URL, an AISIX caller API key, and a model alias available through /v1/messages. The alias can use Anthropic directly or another supported provider through AISIX translation.

Prerequisites​

  • A running AISIX gateway that your application can reach.
  • A configured model alias available through /v1/messages.
  • A caller API key allowed to use that model alias.
  • Python 3.9 or later.

If AISIX is already deployed for your organization, obtain the gateway URL, model alias, and caller API key from the team that manages it. Otherwise, follow the Open-Source AISIX Gateway Quickstart or AISIX Cloud Quickstart, or contact API7 for Hybrid Cloud access.

To configure an Anthropic-backed model alias for either product, follow Anthropic. The SDK client configuration is the same for AISIX Cloud and the open-source AISIX gateway.

Request Flow​

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


The application sends the caller API key and AISIX model alias. AISIX authorizes the caller, resolves the alias, and supplies the stored provider credential when it calls the upstream model.

Configure the SDK​

Set the caller API key, model alias, and gateway base URL:

export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="claude-sonnet-prod"
export AISIX_BASE_URL="http://127.0.0.1:3000"

The Anthropic SDK appends /v1/messages to the base URL. Do not include /v1 in AISIX_BASE_URL.

Install the Anthropic SDK​

Create and activate a Python virtual environment:

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

Install the Anthropic SDK:

python -m pip install anthropic

Create a Client Example​

Create the following client:

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["AISIX_MODEL"],
  max_tokens=128,
  messages=[{"role": "user", "content": "Say hello from AISIX."}],
)

print(message.content[0].text)

Run the example:

python anthropic-sdk-example.py

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

The SDK sends POST /v1/messages with the AISIX model alias. AISIX authenticates the caller API key, checks the model allowlist, resolves the alias, and returns an Anthropic-style message response.

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-Style Messages API.

If the SDK Request Fails​

First send a direct request to /v1/messages with the same caller API key and model alias. If the direct request succeeds, confirm that AISIX_BASE_URL points to the gateway root and does not end in /v1.

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. For an upstream authentication or model error, verify the provider configuration rather than replacing the caller API key.

Clean Up​

Remove the Python environment created here:

deactivate
rm -rf .venv

The gateway resources this example uses were created outside this page. With AISIX Cloud, delete the caller API key, model alias, and provider key from the dashboard. With the open-source AISIX gateway, remove their entries from resources.yaml and reload.

Next Steps​

You have now called AISIX from an Anthropic SDK client. Continue with Anthropic-Style Messages API for endpoint behavior, Streaming for streamed responses, or Anthropic for upstream configuration.