Anthropic SDK Integration

Aurora exposes the Anthropic Messages API wire format at /v1/messages when ENABLE_ANTHROPIC_INGRESS=true is set. The official Anthropic SDK targets that path automatically � you just point its base_url at Aurora's origin.

This page is a quick-start. For the full request/response shape, supported features, and gotchas, see Anthropic Messages API.

Configuration

Point the Anthropic SDK at Aurora's origin (not at /v1 or /anthropic):

from anthropic import Anthropic
 
client = Anthropic(
    base_url="http://your-aurora-host",   # SDK appends /v1/messages
    api_key="sk-aurora-...",
)
 
message = client.messages.create(
    model="anthropic/claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  baseURL: "http://your-aurora-host",
  apiKey: "sk-aurora-...",
});
 
const message = await client.messages.create({
  model: "anthropic/claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(message.content[0].text);

The SDK appends /v1/messages to whatever base_url you give it. Setting base_url="http://your-aurora-host/v1" works too, but you must not set it to .../anthropic � that path does not exist on Aurora.

Enable the ingress

The native /v1/messages endpoint is opt-in. Set ENABLE_ANTHROPIC_INGRESS=true in your .env and restart Aurora. The default is off so that OSS deployments that only speak OpenAI do not accidentally expose the second surface.

What works

Through /v1/messages, Aurora supports:

• The full Anthropic request/response shape (no translation to OpenAI format)
• Streaming (SSE)
• Tool use, parallel tool calls, and tool results
• System prompt (the top-level system field, which Aurora guardrails can target)
• Extended thinking (thinking: {type: "enabled", budget_tokens: ...})
• Prompt caching (cache_control: {type: "ephemeral"}) � Aurora forwards it and reports cache_creation_input_tokens and cache_read_input_tokens in the usage
• Token counting via /v1/messages/count_tokens

What does not work

/v1/messages is the chat surface. The following Anthropic features live on separate endpoints and are not exposed through Aurora's translation path:

• File uploads (Anthropic Files API) � use provider passthrough at /p/anthropic/v1/files
• Vision with pre-uploaded files � embed images as base64 in the message or use passthrough
• Batch processing (Anthropic Message Batches API) � use passthrough at /p/anthropic/v1/messages/batches
• Admin / organization endpoints � use passthrough or your Anthropic dashboard

Passthrough vs native ingress

Aurora has two ways to reach Anthropic from the SDK:

You almost always want the native ingress. Use passthrough when you specifically need a non-chat Anthropic endpoint.

Model routing

When the SDK sends model: "claude-sonnet-4-5" to /v1/messages, Aurora resolves the alias chain and forwards to the configured Anthropic provider. If you have multiple Anthropic providers (anthropic-prod, anthropic-staging), target them by name in the model string � model: "anthropic-prod/claude-sonnet-4-5". See Aliases for renaming and Provider Pools for load balancing.

Gotchas

• anthropic-version header is required. Aurora rejects requests without it. The SDK adds it automatically; if you write raw HTTP, include anthropic-version: 2023-06-01.
• max_tokens is required. Claude will 400 without it. The SDK adds a default; raw HTTP must set it.
• Managed keys are honored. A request authenticated with a managed key still uses the same ingress � Aurora applies the key's provider/model/user_path policy before forwarding.
• Stop reasons are the Anthropic shape. The OpenAI chat-completions translation has a slightly different finish_reason mapping; if you need the canonical Claude behavior, use the Anthropic SDK against this ingress.
• Do not point the SDK at passthrough and expect translation. Passthrough is raw. Use the native ingress unless you have a specific reason not to.

Related

• Anthropic Messages API � full reference
• Anthropic provider guide � provider configuration
• API: Passthrough � for non-chat Anthropic endpoints