9router-Python – Python SDK for the 9Router AI gateway (35 models)

Python SDK + CLI for the 9Router AI gateway.

One tiny library to talk to an OpenAI-compatible gateway that routes to Gemini, NVIDIA, OpenRouter, Groq, Ollama, Tavily and Exa — chat, images, TTS, STT, embeddings and web search/fetch — all through a single local endpoint, with automatic fallback between providers.

$ pip install 9router-python

Everything runs through one base URL. Configure once, use everywhere.

$ pip install 9router-python
$ ninerouter chat "Hello, world!" --stream
Hello! 👋 How can I help you today?

That's it. One gateway, one SDK, every capability.

from ninerouter import NineRouter

with NineRouter() as client:
    reply = client.chat("Explain a monad in one sentence")
    print(reply.text)

Stream tokens as they arrive:

for chunk in client.chat_stream("Write a haiku about Python"):
    print(chunk.content, end="", flush=True)
image = client.image("a watercolor of mountains at sunrise")
open("out.png", "wb").write(image.content)
audio = client.tts("Olá, mundo!", voice="pt-BR-FernandaNeural", model="gemini/gemini-3.1-flash-tts-preview")
open("speech.wav", "wb").write(audio)
text = client.stt(file=("recording.wav", open("recording.wav", "rb").read()))
print(text.text)
vector = client.embeddings("The quick brown fox")[0]
curl_similarity = sum(a * b for a, b in zip(vector, other))
results = client.web_search("9Router open source")
for r in results.results:
    print(r.title, "-", r.url)

page = client.web_fetch("https://example.com")
print(page.content.text)
ninerouter                          # help
ninerouter health                   # gateway status
ninerouter models --kind chat       # list chat models
ninerouter chat "Hello" --stream    # chat with streaming
ninerouter embed "text"             # embedding vector
ninerouter image "a red fox" --out fox.png
ninerouter tts "Hello" --voice pt-BR-FernandaNeural
ninerouter stt recording.wav
ninerouter web search "9Router"
ninerouter web fetch https://example.com
ninerouter config                   # show effective config

Resolution order: CLI flags > environment variables > defaults.

export NINEROUTER_URL="http://localhost:20128"
export NINEROUTER_KEY="sk-..."     # optional if gateway has auth disabled

The key is only sent when non-empty, so a gateway running with requireApiKey=false

works out of the box.

SSE-by-default: the gateway often streams SSE even whenstream

isn't set — the client parses both JSON and SSE transparently.TTS: some OpenRouter TTS models return502

upstream errors; prefer agemini/*

TTS model.STT: multipart upload withgemini/*

orgroq/whisper-*

models.Web search/fetch use(notprovider

model

), e.g.tavily

,exa

, or thesearch-combo

.Combos(owned_by: "combo"

, likeCode

) auto-fallback across providers — great defaults for chat.

pip install -e .[dev]
pytest                     # mocked unit tests
pytest -m live             # live tests (needs a running gateway)

Requires Python 3.9+.

9Router gives you keyless access to dozens of AI providers with automatic fallback, so your app keeps working even if one provider's quota or free tier runs out. This SDK removes the friction: you get a typed, tested Python client and a friendly CLI without caring about which endpoint each provider uses.

This SDK is a thin HTTP client — it does not hold AI provider keys, does not upload your prompts anywhere other than the gateway you point it at, and ships no telemetry.

No secrets in the client. An optional API key is read from the environment (NINEROUTER_KEY

) and sent only to your configured gateway.Nothing leaves your network except to the gateway you configure. The SDK never sends data to the SDK author or any third party.The gateway holds the keys. Provider API keys (Gemini, NVIDIA, Tavily, …) live inyour9Router gateway onyourmachine/VM — not in this library.Supply-chain hygiene. Only two runtime dependencies (httpx

,typer

), both widely trusted. CI runs unit tests on every push across Python 3.9/3.11/3.13.No-secrets guardrail. A test in CI scans the repo for committed credentials and fails the build if anything slips in.

See SECURITY.md for the full policy and how to report a vulnerability privately.

MIT © (ChristopherDond)

SDK Python + CLI para o gateway de IA 9Router.

Um único pacote para conversar com um gateway compatível com a API da OpenAI que roteia Gemini, NVIDIA, OpenRouter, Groq, Ollama, Tavily e Exa — chat, imagens, TTS, STT, embeddings e busca web, com fallback automático entre provedores.

pip install 9router-python
ninerouter chat "Olá, mundo!" --stream

Consulte a seção Features e Quickstart acima — a API e o CLI são idênticos. Para configurar, veja Configuration.

from ninerouter import NineRouter

with NineRouter() as client:
    print(client.chat("Me conta uma piada"))

⬆ back to top