Python (OpenAI client)

Use nRouter as a drop-in proxy with the official OpenAI Python SDK by setting the base URL, enabling team budgets, guardrails, and multi-model routing.

The official openai Python SDK integrates with nRouter as a zero-refactor drop-in proxy by pointing base_url to https://api.nrouter.ai/v1.

Configure NROUTER_API_KEY to access unified smart AI routing across providers:

Zero code changes: Retain existing openai client methods, classes, and streaming workflows without extra dependencies.
Enterprise controls: Automated provider fallbacks, exact list-price cost tracking, and server-side guardrails.

Installation

pip install openai

Setup & Chat Completion

Set your virtual API key in your environment:

export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"

Initialize the client with nRouter's OpenAI-compatible API:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[
        {"role": "system", "content": "You are a concise technical writer."},
        {"role": "user", "content": "Explain zero-markup model pricing."},
    ],
)

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

Streaming Responses

Stream tokens via Server-Sent Events (SSE):

stream = client.chat.completions.create(
    model="claude-haiku-4-5-20251001",
    messages=[{"role": "user", "content": "Write a short poem about distributed queues."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

Routing & Telemetry

Configure routing options via request parameters and inspect gateway telemetry:

Direct & Fallback: Pass nrouter_fallbacks in the request body for automatic provider failover (see Per-Request Options).
Auto Model Selection: Use nrouter/auto to route by cost or capability configured in Router Settings.
FinOps Telemetry: Extract x-nr-request-cost and x-nr-model headers via client.chat.completions.with_raw_response.

Error Handling

Errors map to standard HTTP status codes documented in Errors & Rate Limits and unwrap to openai exceptions:

import openai

try:
    response = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": "Execute task."}],
    )
except openai.BadRequestError as e:
    print("Guardrail or parameter error:", e)
except openai.AuthenticationError:
    print("Authentication failed: Check your NROUTER_API_KEY.")
except openai.RateLimitError:
    print("Rate limit reached. Back off before retry.")
except openai.APIError as e:
    print(f"Gateway error ({e.code}): {e.message}")

Next Steps

Python SDK Guide — Official native nRouter Python SDK
LangChain Integration — Building chains and RAG pipelines
Chat Completions API — Direct HTTP wire specifications
Migrate to nRouter — Zero-downtime migration guide
nRouter vs OpenRouter — Architecture and pricing comparison
Routing for AI agents — Agent routing design patterns
nRouter vs Vercel AI Gateway — Comparison overview