9router Gateway

---
name: 9router-gateway
description: Use when interacting with 9Router API gateway, managing local/remote AI proxies, fallback chains, auto-routing, and OpenAI-compatible endpoints for chat, image, TTS, embeddings, and web search. Triggers on "9router", "9Router API", "NINEROUTER_URL", "gateway de IA", "auto-fallback".
metadata:
  origin: decolua/9router
---

# 9Router Gateway

Local/remote AI gateway exposing OpenAI-compatible REST endpoints with automatic failover and provider aggregation.

## When to Use

- "Route this call through 9Router"
- "Set up NINEROUTER_URL fallback chain"
- "Quota exhausted, rotate the combo"
- "List models on the local gateway"
- "Auto-fallback for chat/image/TTS"

## Setup & Endpoints

```bash
export NINEROUTER_URL="http://localhost:20128"
export NINEROUTER_KEY="sk-..."
```

- Chat / Completions: `$NINEROUTER_URL/v1/chat/completions`
- Models:
  - Chat: `$NINEROUTER_URL/v1/models`
  - Image: `$NINEROUTER_URL/v1/models/image`
  - TTS: `$NINEROUTER_URL/v1/models/tts`
  - Web: `$NINEROUTER_URL/v1/models/web`

## Error Handling
- **401**: Check/refresh `NINEROUTER_KEY`.
- **503 All accounts unavailable**: Quota exhausted across provider chain; rotate combo or update primary provider model.

## Intent-Based Routing (Batch 16, #46)

Expose capability names ("text-summarizer") instead of model names. The
gateway maps capability -> contracted model + fallback/retry/timeout, so
app code never names a model and routing changes need no redeploy.
Decide each change with the latency x quality x cost tradeoff written
down; models are commodities, the capability contract is the API.