Anthropic · Python

The Anthropic Python SDK accepts a base_url argument on the client. Point it at the gateway and the standard client.messages.create calls route through. This recipe targets claude-haiku-4-5-20251001 which the gateway's classifier promotes for the simple and medium tiers.

Drop-in switch

client = anthropic.Anthropic(
    base_url="https://gateway.iq-routing.com",
    api_key="gw_live_xxxxxxxx",
)

The gateway exposes the Anthropic surface at /v1/messages (no /v1 prefix in the SDK's internal routing; the SDK appends /v1/messages itself). Pass the gateway origin without /v1.

Verify it routes

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.iq-routing.com",
    api_key=os.environ["IQ_GATEWAY_KEY"],
    timeout=60.0,
    max_retries=0,
)

response = client.messages.with_raw_response.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=64,
    messages=[{"role": "user", "content": "Summarise: routing-aware gateway."}],
)

print("X-Request-Id:", response.headers.get("x-request-id"))
parsed = response.parse()
print("Stop reason:", parsed.stop_reason)
print(parsed.content[0].text)

Drop the script into a fresh venv, pip install anthropic, set IQ_GATEWAY_KEY in your environment, run. The X-Request-Id header is the gateway's correlation handle.

The model pin (claude-haiku-4-5-20251001) keeps the call within the operator's key constraints (Haiku only). If you pass model="auto" the gateway's classifier picks; expect Haiku for short prompts, fall-through to OpenAI mini-tier for long-context summarisation when an OpenAI provider is configured on the org.

Using capability aliases

The cap:<name> syntax in the model field tells the gateway to pick a concrete model at routing time based on the capability's stable intent rather than a pinned model id. The operator's per-org overrides plus the focus-mode bias plus the circuit-breaker state shape the resolved tuple. The six default capabilities are reason-heavy, tool-call-strict, long-context-128k, vision, cheap-fast, and json-mode.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.iq-routing.com",
    api_key=os.environ["IQ_GATEWAY_KEY"],
)

message = client.messages.create(
    model="cap:reason-heavy",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Plan the migration in three phases."}],
)

The resolved provider plus model surface in the x-iq-routing response header (a JSON-encoded payload with chosen_provider and chosen_model fields, among others), so the SDK consumer can inspect which concrete model handled the request. See the capability aliases docs for the full resolver decision tree plus the override mechanics. The operator can override the default capability mapping via the capabilities dashboard editor at /settings/capabilities.

Common gotchas

The Anthropic SDK's default max_retries is 2. The gateway's 429 already cooldowns; SDK retries on top double-bill the cooldown window. Set max_retries=0.

stream=True works against the gateway. The SDK's MessageStreamManager consumes the SSE just as it does against api.anthropic.com. The X-Request-Id header is on the underlying HTTP response, available via the event.message.id field on each streamed chunk for correlation against the gateway's requests view.

Tool use (tools parameter) routes through the gateway transparently. The gateway forwards the tool-use blocks in both directions without rewriting the schema. Beta features (anthropic-beta header) are passed through: the gateway forwards the header verbatim to the upstream provider and does not evaluate it or reject the request over it. Every error body on this surface carries a request_id field for correlation against the requests view.

When every upstream provider is exhausted the gateway returns 503 (rendered as an overloaded_error in the Anthropic error body). That response does not carry a Retry-After header, so back off on your own schedule. The one place the gateway does emit Retry-After is a 429 (the per-team rate-limit window); the Anthropic SDK does not auto-retry on either, so a caller-side queue should read Retry-After on the 429 and apply its own backoff on the 503.

Try this in the playground

Run this snippet against your gateway key →