# OpenAI SDK (Python)

The OpenAI SDK is the canonical client. It works with LowRouter
unchanged once you set `base_url` and `api_key`.

## Install

```bash
pip install openai
```

## A non-streaming completion

```python
import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="auto/mistralai/mistral-large-2512",
    messages=[
        {"role": "user", "content": "In one sentence, what is a vector database?"}
    ],
)

print(response.choices[0].message.content)
```

## A streaming completion

```python
stream = client.chat.completions.create(
    model="auto/mistralai/mistral-large-2512",
    messages=[{"role": "user", "content": "Count to 5 slowly"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

## Reading the eco metadata

LowRouter's per-request metadata lives outside the OpenAI schema, so
the typed SDK fields don't surface it. Read it from the raw response:

```python
response = client.chat.completions.create(
    model="auto/mistralai/mistral-large-2512",
    messages=[{"role": "user", "content": "hi"}],
)
extra = response.model_extra or {}
meta = extra.get("lowrouter_metadata", {})
if meta:
    print(f"{meta['carbon_gco2e']:.4f} gCO2e via {meta['provider']} "
          f"({meta['region']})")
```

`response.model_extra` is the canonical Pydantic-v2 escape hatch for
non-schema fields. On older SDK versions the attribute is
`response.__pydantic_extra__`.

## Pinning a region

There is no separate route field. Pin a region by appending a
UN/LOCODE as the fourth segment of the model ID
(`{provider}/{creator}/{model}/{locode}`); omit it to use the default
region:

```python
response = client.chat.completions.create(
    model="vertex/anthropic/claude-opus-4.6/sg-sin",
    messages=[{"role": "user", "content": "hi"}],
)
```

## Async

The async client follows the same pattern:

```python
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.lowrouter.ai/v1",
    api_key=os.environ["LOWROUTER_API_KEY"],
)

async def main():
    r = await client.chat.completions.create(
        model="auto/mistralai/mistral-large-2512",
        messages=[{"role": "user", "content": "hi"}],
    )
    print(r.choices[0].message.content)

asyncio.run(main())
```