Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt

Use this file to discover all available pages before exploring further.

Auriko exposes an OpenAI-compatible API. Your existing chat completions, streaming, and tool calling code works with minimal changes.

​
Get started

Only the client initialization changes: 
# With OpenAI SDK
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# With Auriko SDK
import os
from auriko import Client
client = Client(
    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!"}]
)

​
What’s compatible

Standard OpenAI API features work through Auriko. Some features have model-specific constraints noted below.
FeatureStatus
Chat completionsCompatible
StreamingCompatible
Tool callingCompatible
Legacy functions/function_callAuto-converted to tools/tool_choice
Structured output (json_schema)Compatible
Structured output (json_object)Model-dependent. See Structured output.
Models listCompatible
Async clientCompatible
Error classesCompatible
Retry logicBuilt-in (max 2 retries, exponential backoff)

​
What’s new

Auriko adds capabilities on top of the OpenAI-compatible interface:
  • Routing options — optimize for cost, latency, or throughput across providers. See Routing options.
  • Cost optimization — save 30-70% with cost-optimized routing across providers. See Cost optimization.
  • Prompt caching — automatic cache injection for all supported providers. See Prompt caching.
  • Budget management — set spending limits per workspace, API key, or BYOK provider. See Error codes for budget enforcement behavior.
  • Response headers — every response carries request_id, rate limit headers, and credit usage. See Python SDK.

​
Use OpenAI SDK directly

You don’t need the auriko package at all. The OpenAI SDK works with a base_url override: 
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)
This approach lets you access models from multiple providers (Anthropic, Google, Meta, and others) through the familiar OpenAI client.

​
Error mapping

When using the OpenAI SDK directly, convert errors to typed Auriko errors with map_openai_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. See Error Handling for the full error handling guide.

​
Access routing metadata

Auriko offers three ways to access routing metadata, ordered from most to least ergonomic.

​
With the native Auriko SDK

auriko.Client and auriko.AsyncClient expose routing_metadata as a typed property directly 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)
See the Python SDK Guide for the full native client reference.

​
With AurikoAsyncOpenAI (experimental)

AurikoAsyncOpenAI (experimental) is a drop-in AsyncOpenAI subclass that captures routing metadata automatically on every response. Use it when a framework (OpenAI Agents SDK, LangChain, LlamaIndex, or similar) needs to be given an external 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.

​
With parse_routing_metadata

When you’re using the OpenAI SDK directly (no Auriko client at all), extract routing metadata from responses with parse_routing_metadata(). This function returns None if routing metadata is absent or unparseable, and None on Auriko SDK responses — use response.routing_metadata directly instead. 
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}")
All three options are Python-only. TypeScript consumers can use @auriko/ai-sdk-provider with the Vercel AI SDK, or the OpenAI TS SDK with baseURL: 'https://api.auriko.ai/v1'.
For the full native SDK experience with typed responses and errors, see the Python SDK Guide or TypeScript SDK Guide.