Anthropic SDK: A Custom Base URL Walkthrough

A custom base URL lets you keep the Anthropic SDK while directing requests to a different server. The important distinction is protocol compatibility: changing the destination does not translate requests into another API format. This walkthrough uses Python and separates SDK configuration from the gateway details you must verify.

1. Confirm the API contract

Before changing application code, confirm that your gateway exposes an Anthropic-compatible Messages endpoint. OpenAI SDK compatibility alone is not enough. Ask for the supported route, authentication header, API version, and exact model identifier. Treat these as integration requirements rather than assumptions.

CodeRelay Hub provides a pay-as-you-go, multi-provider endpoint at https://api.coderelayhub.com. For this walkthrough, use that address only after confirming its Anthropic-compatible route and authentication requirements; the hostname alone does not establish either.

2. Install and record the SDK version

Install the official package with python -m pip install anthropic. Import the client with from anthropic import Anthropic. These are the package and client used in Anthropic’s Python examples. ([github.com](https://github.com/anthropics/anthropic-sdk-python))

Record the working dependency version in your lockfile. Test upgrades against the gateway before deploying them. This matters because the SDK automatically supplies an API-version header, and major SDK releases can change that version. A newer client is not automatically a better match for an existing compatibility layer. ([platform.claude.com](https://platform.claude.com/docs/en/api/sdks/python))

3. Set the destination explicitly

The Python client accepts base_url and also supports the ANTHROPIC_BASE_URL environment variable. Prefer an explicit constructor argument during initial testing so the destination is visible beside the credential configuration. ([platform.claude.com](https://platform.claude.com/docs/en/api/sdks/python))

For a gateway confirmed to accept API-key authentication, a minimal constructor is client = Anthropic(base_url="https://api.coderelayhub.com", api_key=os.environ["CODERELAY_API_KEY"], timeout=30.0, max_retries=0). Import os first. The timeout and disabled retries are deliberate diagnostic settings, not universal production defaults.

Supply the gateway credential, not an unrelated direct-provider key. If the gateway requires another authentication scheme, adapt the constructor to its documented example. Do not append a guessed route prefix or the complete Messages resource path to the base address.

4. Send one small request

Set model_id = os.environ["CODERELAY_MODEL_ID"] to the exact identifier shown in your workspace. A display name such as Claude Haiku 4.5 is useful for selection, but do not derive the API identifier by lowercasing or replacing spaces.

Then call message = client.messages.create(model=model_id, max_tokens=64, messages=[{"role": "user", "content": "Reply with one short greeting."}]). This follows the SDK’s Messages request structure while keeping the initial test small. ([github.com](https://github.com/anthropics/anthropic-sdk-python))

For the first run, inspect message.content. When extracting readable output, iterate through the content blocks and print block.text only when block.type == "text". The official example uses this typed-block approach. ([github.com](https://github.com/anthropics/anthropic-sdk-python))

5. Diagnose failures before adding retries

Check failures in a fixed order: destination, route, credentials, model identifier, then request fields. Capture the HTTP status and a sanitized error body. Preserve any request identifier the gateway returns, but exclude authorization headers and sensitive prompts from routine logs.

• Authentication failure: Verify the credential belongs to the gateway and uses its required header.
• Missing resource: Compare the actual outgoing path with the gateway’s documented route.
• Rejected request: Remove optional fields and retry the minimal message.
• Connection failure: Check DNS, TLS, proxy configuration, and network access.

6. Promote the integration deliberately

After the basic request succeeds, test streaming separately. The SDK supports streaming, but your acceptance test should verify the gateway’s event handling, completion signal, and interrupted-response behavior. ([platform.claude.com](https://platform.claude.com/docs/en/api/sdks/python))

Add application-specific timeout and retry policies, then test cancellation and any required tool interactions. Keep endpoint, credential, and model configuration together so staging cannot accidentally inherit production settings. Before rollout, confirm spending controls and inspect one complete request lifecycle without exposing secrets.

Open a free workspace to try it.