ZenRouter

ZenRouter helps an app keep going when an OpenCode Zen model is busy or has reached its limit.

Give it a list of free models and an optional list of paid backups. It tries them in order, remembers a model that needs a short break, and moves on when Zen says that model is temporarily unavailable. Your app gets the normal Chat Completions response plus the name of the model that handled it.

This first release supports OpenCode Zen's Chat Completions endpoint. It is built for server-side TypeScript and Python apps.

What It Does

• Tries free models before paid models.
• Moves to the next model for rate limits, exhausted credits, temporary outages, and unavailable models.
• Respects Zen's Retry-After wait time when it is supplied.
• Avoids wasting requests on models that are still waiting to become available.
• Keeps ordinary failures, such as a bad API key or invalid request, visible instead of quietly trying every model.
• Passes a successful streamed reply straight through. It never restarts a reply after it has begun.

TypeScript

Install the package after it has been published, or use a local npm link while developing it:

npm install @genoventures-labs/zenrouter

import { createZenRouter } from "@genoventures-labs/zenrouter";

const router = createZenRouter({
  apiKey: process.env.OPENCODE_ZEN_API_KEY!,
  freeModels: ["big-pickle", "mimo-v2.5-free", "hy3-free"],
  paidModels: ["deepseek-v4-flash", "qwen3.5-plus"],
});

const result = await router.chat({
  messages: [{ role: "user", content: "Explain this function." }],
});

console.log(`Used ${result.pool}: ${result.model}`);
const completion = await result.response.json();

For a streamed reply, add stream: true to the request and read the returned response as usual:

const result = await router.chat({
  stream: true,
  messages: [{ role: "user", content: "Explain this function in a few lines." }],
});

for await (const chunk of result.response.body!) {
  process.stdout.write(new TextDecoder().decode(chunk));
}

Python

The Python package lives in python. From that folder, install it into your environment:

pip install .

import os

from zenrouter import ZenRouter

router = ZenRouter(
    api_key=os.environ["OPENCODE_ZEN_API_KEY"],
    free_models=["big-pickle", "mimo-v2.5-free"],
    paid_models=["deepseek-v4-flash"],
)

result = router.chat({
    "messages": [{"role": "user", "content": "Explain this code."}],
})

print(f"Used {result.pool}: {result.model}")
print(result.response.read().decode())

Keep Your Key Safe

ZenRouter needs your OpenCode Zen API key, so create the router in your server, command-line program, or Python service.

Do not put OPENCODE_ZEN_API_KEY in browser JavaScript, a mobile app, a public repository, or a frontend .env file. A website should send requests to its own backend, and that backend should use ZenRouter.

Free-model availability and data handling can vary. Review the current Zen model list, pricing, privacy information, and your own spending limits before turning on paid backups.

Development

npm install
npm run typecheck
npm test
npm run build

Run the Python tests with the package source on the import path:

PYTHONPATH=python python -m unittest discover -s python/tests -v