OpenAI Compatibility

Auriko exposes an OpenAI-compatible API. If you already use the OpenAI SDK, change your client initialization to point at Auriko and every call works the same way.

Update client initialization

Change the client initialization to point at Auriko:

Python

# With OpenAI SDK
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# With Auriko — just change the init
import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

# Everything else stays the same
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

TypeScript

// With OpenAI SDK
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "sk-..." });

// With Auriko — just change the init
import OpenAI from "openai";
const client = new OpenAI({
    apiKey: process.env.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/v1",
});

// Everything else stays the same
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
});

Check compatibility

Standard OpenAI API features work through Auriko, including chat completions, the Response API, streaming, tool calling, structured output (json_schema), error classes, async clients, and the models list endpoint. Some features have special handling:

Feature	Behavior
Response API	Preview. See Response API overview and API reference.
Legacy `functions`/`function_call`	Auriko auto-converts to `tools`/`tool_choice`
Structured output (`json_object`)	Model-dependent. See Structured output.

Use additional features

Auriko adds capabilities on top of the OpenAI-compatible interface:

Routing options: Optimize for cost, latency, or throughput across providers.
Cost optimization: Auriko computes the expected cost of each request at every available provider and routes to the cheapest one.
Prompt caching: Auriko optimizes prompt caching automatically, reducing cost and latency on repeated requests.
Budget management: Set spending limits per workspace, API key, or BYOK provider. See Error codes for the budget_exhausted code.
Response headers: Every response includes request_id, rate limit headers, and credit usage. See Python SDK or TypeScript SDK.

Use OpenAI SDK directly

You can use the OpenAI SDK with a base_url override instead of the Auriko package:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello from Claude via Auriko!"}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/v1",
});

const response = await client.chat.completions.create({
    model: "claude-sonnet-4-20250514",
    messages: [{ role: "user", content: "Hello from Claude via Auriko!" }],
});
console.log(response.choices[0].message.content);

This gives you access to models from multiple providers (Anthropic, Google, Meta, and others) through the OpenAI client. For typed routing metadata and error mapping, use the Auriko SDK (Python, TypeScript) instead.

Map errors

If you use the OpenAI SDK directly, Auriko errors arrive as generic openai.APIStatusError. You can convert them to typed Auriko errors with map_openai_error() to branch on specific error codes like budget_exhausted or rate_limit_error:

import os
import openai
from auriko import map_openai_error, RateLimitError, PermissionDeniedError

client = openai.OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except openai.APIStatusError as e:
    auriko_error = map_openai_error(e)
    if isinstance(auriko_error, RateLimitError):
        # budget_exhausted is a 429 rate_limit_error; branch on .code if needed
        if auriko_error.code == "budget_exhausted":
            print(f"Budget exhausted: {auriko_error.message}")
        else:
            print(f"Rate limited. Retry after: {auriko_error.retry_after_seconds}s")
    elif isinstance(auriko_error, PermissionDeniedError):
        print(f"Permission denied (code={auriko_error.code}): {auriko_error.message}")
    else:
        raise auriko_error

map_openai_error() is Python-only. TypeScript users get typed errors automatically with the Auriko SDK. See Error Handling for the full guide.

Access routing metadata

Every Auriko response includes routing metadata: which provider handled the request, the cost, and latency. How you access it depends on which SDK you use.

With the Auriko SDK

Both the Python and TypeScript SDKs expose routing_metadata as a typed property on each response:

from auriko import Client

client = Client()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.routing_metadata.provider)

import { Client } from "@auriko/sdk";

const client = new Client();
const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.routing_metadata?.provider);

See the Python SDK or TypeScript SDK for the full client reference.

With the OpenAI SDK

Auriko includes routing metadata in every response. If you use the OpenAI SDK, the auriko Python package provides two helpers to extract it with full typing: parse_routing_metadata() extracts routing metadata from an OpenAI SDK response:

from auriko.route_types import parse_routing_metadata

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
metadata = parse_routing_metadata(response)
if metadata:
    print(f"Provider: {metadata.provider}")
    if metadata.cost:
        print(f"Cost: ${metadata.cost.usd}")

AurikoAsyncOpenAI (experimental) is a drop-in AsyncOpenAI subclass that captures routing metadata on every response. Use it when a framework (OpenAI Agents SDK, LangChain, LlamaIndex) requires an AsyncOpenAI instance:

import asyncio
from auriko import AurikoAsyncOpenAI

async def main():
    client = AurikoAsyncOpenAI()
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(client.last_routing_metadata.provider)

asyncio.run(main())

Install with pip install "auriko[openai-compat]". See AurikoAsyncOpenAI for framework wiring details.

These helpers are Python-only. For typed routing metadata in TypeScript, use the Auriko SDK or @auriko/ai-sdk-provider with the Vercel AI SDK.

Resources

Python SDK — full native client reference
TypeScript SDK — TypeScript client reference
Error handling — complete error handling guide

​Update client initialization

​Python

​TypeScript

​Check compatibility

​Use additional features

​Use OpenAI SDK directly

​Map errors

​Access routing metadata

​With the Auriko SDK

​With the OpenAI SDK

​Resources

Update client initialization

Python

TypeScript

Check compatibility

Use additional features

Use OpenAI SDK directly

Map errors

Access routing metadata

With the Auriko SDK

With the OpenAI SDK

Resources