> ## 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.

# OpenAI Compatibility

> Minimal changes to your existing OpenAI code

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

```python theme={null}
# 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

```typescript theme={null}
// 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](/response-api/overview) and [API reference](/api-reference/create-response). |
| Legacy `functions`/`function_call` | Auriko auto-converts to `tools`/`tool_choice`                                                                     |
| Structured output (`json_object`)  | Model-dependent. See [Structured output](/guides/structured-output).                                              |

## Use additional features

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

* **[Routing options](/guides/routing-options):** Optimize for cost, latency, or throughput across providers.
* **[Cost optimization](/guides/cost-optimization):** Auriko computes the expected cost of each request at every available provider and routes to the cheapest one.
* **[Prompt caching](/guides/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](/contract/error-codes) for the `budget_exhausted` code.
* **Response headers:** Every response includes `request_id`, rate limit headers, and credit usage. See [Python SDK](/sdk/python#read-response-headers) or [TypeScript SDK](/sdk/typescript#read-response-headers).

## Use OpenAI SDK directly

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

<CodeGroup>
  ```python Python OpenAI theme={null}
  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)
  ```

  ```typescript TypeScript OpenAI theme={null}
  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);
  ```
</CodeGroup>

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](/sdk/python), [TypeScript](/sdk/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`:

```python theme={null}
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
```

<Note>
  `map_openai_error()` is Python-only. TypeScript users get typed errors automatically with the [Auriko SDK](/sdk/typescript). See [Error Handling](/guides/error-handling) for the full guide.
</Note>

## 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:

<CodeGroup>
  ```python Python theme={null}
  from auriko import Client

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

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

See the [Python SDK](/sdk/python) or [TypeScript SDK](/sdk/typescript) 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:

```python theme={null}
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:

```python theme={null}
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`](/sdk/python#use-with-openai-compatible-frameworks) for framework wiring details.

<Note>
  These helpers are Python-only. For typed routing metadata in TypeScript, use the [Auriko SDK](/sdk/typescript) or [`@auriko/ai-sdk-provider`](/frameworks/vercel-ai-sdk) with the Vercel AI SDK.
</Note>

## Resources

* [Python SDK](/sdk/python) — full native client reference
* [TypeScript SDK](/sdk/typescript) — TypeScript client reference
* [Error handling](/guides/error-handling) — complete error handling guide