# Anthropic SDK

Point the Anthropic Python SDK at an AISIX 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[​](#prerequisites "Direct link to 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, [get started with AISIX OSS](https://docs.api7.ai/ai-gateway/getting-started/gateway-quickstart.md) or [AISIX Enterprise](https://docs.api7.ai/ai-gateway/getting-started/aisix-cloud-quickstart.md), or [contact API7](https://api7.ai/contact) for AISIX Cloud access.

To configure an Anthropic-backed model alias for any AISIX product, follow [Anthropic](https://docs.api7.ai/ai-gateway/providers/anthropic.md). The SDK client configuration is the same for AISIX Enterprise, AISIX Cloud, and AISIX OSS.

## Request Flow[​](#request-flow "Direct link to Request Flow")

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

<br />

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[​](#configure-the-sdk "Direct link to Configure the SDK")

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

```
# AISIX_BASE_URL is the gateway origin without a trailing slash or /v1

# The local quickstarts use http://127.0.0.1:3000

export AISIX_BASE_URL="YOUR_AISIX_GATEWAY_URL"

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

export AISIX_MODEL="claude-sonnet-prod"
```

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

### Install the Anthropic SDK[​](#install-the-anthropic-sdk "Direct link to 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-a-client-example "Direct link to 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[​](#compatibility-boundaries "Direct link to 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](https://docs.api7.ai/ai-gateway/endpoints/anthropic-messages.md).

## If the SDK Request Fails[​](#if-the-sdk-request-fails "Direct link to 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[​](#clean-up "Direct link to 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 Enterprise or AISIX Cloud, delete the caller API key, model alias, and provider key from the dashboard. With AISIX OSS, remove their entries from `resources.yaml` and reload.

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

You have now called AISIX from an Anthropic SDK client. Continue with [Anthropic-Style Messages API](https://docs.api7.ai/ai-gateway/endpoints/anthropic-messages.md) for endpoint behavior, [Streaming](https://docs.api7.ai/ai-gateway/endpoints/streaming.md) for streamed responses, or [Anthropic](https://docs.api7.ai/ai-gateway/providers/anthropic.md) for upstream configuration.
