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://lowrouter.ai/api/v1",
    api_key=os.environ["LOWROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="lowrouter/auto",
    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="lowrouter/auto",
    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="lowrouter/auto",
    messages=[{"role": "user", "content": "hi"}],
)
extra = response.model_extra or {}
eco = extra.get("lowrouter", {}).get("eco")
if eco:
    print(f"{eco['carbon_per_1k_tokens_g']:.3f} gCO2e/1k tokens "
          f"({eco['accuracy']})")

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 with extra_body

The OpenAI SDK passes unknown kwargs through extra_body:

Python

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "hi"}],
    extra_body={"route": {"region": "eu-west"}},
)

If you need this on every request, make it a default by wrapping the client:

Python

def make_client(region="eu-west"):
    base = OpenAI(
        base_url="https://lowrouter.ai/api/v1",
        api_key=os.environ["LOWROUTER_API_KEY"],
        default_headers={"X-LowRouter-Region": region},
    )
    return base

X-LowRouter-Region is honoured the same as route.region in the body.

Async

The async client follows the same pattern:

Python

import asyncio
from openai import AsyncOpenAI

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

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

asyncio.run(main())