domains / general / routerbase-model-gateway / routerbase-model-gateway

routerbase-model-gateway

Skill card

combined

Both copies describe the same RouterBase OpenAI-compatible gateway integration, but each contains material steps the other lacks. The davepoon copy provides a detailed debug checklist, a specific output contract, and guardrails for high-impact use cases. The sickn33 copy provides a structured four-step workflow (classify workload, configure client, validate model IDs via live catalog, design fallbacks), a live catalog curl command, and a retryable-error classification pattern. Crowning one would hide the other's unique validation and debugging procedures.

Repositories

Other copies

Combined skill

---
name: routerbase-model-gateway
category: ai-ml
description: Integrate and route AI model requests through RouterBase. Use when migrating OpenAI-compatible clients, choosing model IDs, configuring fallbacks, or building chat, image, video, audio, speech, and embedding workflows.
---

# RouterBase Model Gateway

Use [routerbase](https://routerbase.com/) as an OpenAI-compatible model gateway for chat, image, video, audio, speech, and embedding workloads. This skill helps agents migrate existing SDK clients, keep credentials private, choose model IDs, and document safe fallback behavior.

## When to Use This Skill

- The user wants to migrate an OpenAI SDK or OpenAI-compatible integration to RouterBase.
- The user needs a model routing plan across cost, latency, quality, context length, streaming, tool calling, JSON mode, or vision requirements.
- The user is adding chat, image, video, audio, speech, or embedding calls to an application.
- The user is debugging RouterBase auth, endpoint, model ID, streaming, media, or payload issues.
- The user needs documentation or a smoke-test checklist for a RouterBase integration.

## How to Use

### 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.

```python
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)
```

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: process.env.ROUTERBASE_BASE_URL || "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.

```bash
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.

```js
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.

## 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

When recommending models, return a table like this:

```markdown
| Use case | Primary model | Fallback model | Reason | Validation |
| --- | --- | --- | --- | --- |
| Support chat | model-id | model-id | Low latency and tool support | Run fixture prompts and compare output shape |
```

Treat model IDs, pricing, and availability as live data. If a live catalog check is not possible, mark examples clearly and tell the user what must be verified before production.

## Debug Checklist

- Authentication: missing `ROUTERBASE_API_KEY`, wrong environment, or server-side secret not loaded.
- Endpoint: missing `/v1`, wrong media endpoint, or client still pointing at another provider.
- Model ID: unavailable, misspelled, disabled for the account, or unsupported for the requested modality.
- Request shape: unsupported field, invalid content part, invalid tool schema, or model-specific parameter mismatch.
- Streaming: client does not consume Server-Sent Events or SDK chunks correctly.
- JSON mode: missing `response_format` or no downstream schema validation.
- Async media: task ID not persisted, polling has no timeout, or generated media is not stored before temporary URLs expire.

## Guardrails

- Never paste, infer, print, or log real API keys.
- Never put RouterBase keys in browser code, mobile apps, screenshots, or public repositories.
- Do not retry authentication, invalid model, validation, or policy errors blindly.
- Do not claim example model IDs, pricing, or availability are permanent facts.
- Validate model-specific support for streaming, tool calling, JSON mode, vision, context length, media size, and async behavior.
- Require human review for high-impact medical, legal, financial, safety, security, or compliance use cases.

## Output

Return:

1. The target endpoint or base URL.
2. Required environment variables.
3. Files to change or create.
4. A minimal request example.
5. A model routing table.
6. Fallback and retry behavior.
7. Validation or smoke-test steps.
8. Remaining assumptions that must be checked against live RouterBase docs or account access.