RouterBase Model Gateway

Overview

Use routerbase when an application needs one OpenAI-compatible API surface for model routing across GPT, Claude, Gemini, image, video, audio, and embedding workloads. This skill helps agents migrate existing OpenAI SDK calls, document model-selection tradeoffs, and produce safe implementation snippets without exposing credentials.

RouterBase model availability, pricing, and provider capabilities can change, so treat examples as starting points and verify current catalog data before production recommendations.

When to Use This Skill

• Use when migrating an OpenAI-compatible client to RouterBase by changing the base URL and model ID.
• Use when selecting primary and fallback models for chat, reasoning, vision, media generation, audio, or embeddings.
• Use when debugging RouterBase request setup, headers, environment variables, streaming, tool calls, JSON mode, or multimodal payloads.
• Use when documenting an internal model-routing plan that balances cost, latency, quality, and provider redundancy.

How It Works

Step 1: Classify the Workload

Identify the modality and hard constraints before choosing a model:

• Modality: chat, vision, image, video, audio, embeddings, or mixed.
• Quality target: draft, production, high-stakes review, or automated background task.
• Runtime constraints: latency budget, context length, streaming, JSON mode, tool calling, and retry tolerance.
• Business constraints: price ceiling, provider preference, regional requirements, and fallback rules.

Step 2: Configure the OpenAI-Compatible Client

Keep the RouterBase API key server-side in an environment variable such as ROUTERBASE_API_KEY. Do not put keys in browser, mobile, or public repository code.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTERBASE_API_KEY"],
    base_url="https://routerbase.com/v1",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{"role": "user", "content": "Write one sentence about model routing."}],
)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: "https://routerbase.com/v1",
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-flash",
  messages: [{ role: "user", content: "Write one sentence about model routing." }],
});

console.log(response.choices[0].message.content);

Step 3: Validate Model IDs and Capabilities

When credentials and network access are available, check the live catalog before locking in a model ID or price-sensitive recommendation.

curl "https://routerbase.com/api/v1/models?task=chat" \
  -H "Authorization: Bearer $ROUTERBASE_API_KEY"

Confirm feature assumptions with a small request fixture:

• Streaming works when stream: true is set.
• Tool calling accepts the exact schema used by the app.
• JSON mode returns parseable output and still passes application validation.
• Vision or media payloads use the expected OpenAI-compatible content shape.

Step 4: Design Fallbacks Conservatively

Use explicit application-level fallbacks unless the user's RouterBase account already has a smart-routing policy configured.

const modelPlan = [
  "anthropic/claude-sonnet-4-6",
  "google/gemini-2.5-flash",
];

for (const model of modelPlan) {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    if (!isRetryableRouterBaseError(error)) throw error;
  }
}

Treat transient network errors, timeouts, rate limits, and server errors as candidates for retry. Do not blindly retry authentication failures, invalid model IDs, validation errors, or policy refusals.

Examples

Migration Checklist

When converting an existing OpenAI SDK integration:

1. Change the base URL to https://routerbase.com/v1.
2. Read ROUTERBASE_API_KEY from server-side environment configuration.
3. Replace the model name with a RouterBase model ID that matches the task.
4. Preserve standard OpenAI request fields unless RouterBase documentation says otherwise.
5. Run one minimal smoke test before shipping.

Routing Plan Format

Use this table when recommending a model strategy:

…