omni-combos-routing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

Create and manage routing combos with 19 strategies (priority, weighted, round-robin, Auto-combo, and more). Configure fallback chains, test routing outcomes, and retrieve combo metrics.

使用 19 种策略（priority、weighted、round-robin、Auto-Combo 等）创建并管理路由组合。配置故障转移链、测试路由结果并获取组合指标。

Authentication

身份验证

All requests require a valid Bearer token or session cookie. Obtain a token via

POST /api/auth/login

or configure

REQUIRE_API_KEY=false

for local development.

所有请求都需要有效的 Bearer 令牌或会话 Cookie。通过

POST /api/auth/login

获取令牌，或在本地开发时配置

REQUIRE_API_KEY=false

。

Endpoints

端点

GET /api/combos

List routing combos

bash

curl http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

列出路由组合

bash

curl http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos

Create routing combo

bash

curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

创建路由组合

bash

curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/combos/{id}

Get combo by ID

bash

curl http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

根据 ID 获取组合

bash

curl http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

PUT /api/combos/{id}

Update combo

Partial update: the body is merged onto the stored combo, so a field left out keeps its current value. An array that IS sent replaces the stored one outright.

bash

curl -X PUT http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

更新组合

部分更新：请求体会与已存储的组合合并，因此未传入的字段会保留当前值。如果传入数组，则会直接整体替换已存储的数组。

bash

curl -X PUT http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /api/combos/{id}

Update combo

Partial update: the body is merged onto the stored combo, so a field left out keeps its current value. An array that IS sent replaces the stored one outright.

bash

curl -X PATCH http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

更新组合

部分更新：请求体会与已存储的组合合并，因此未传入的字段会保留当前值。如果传入数组，则会直接整体替换已存储的数组。

bash

curl -X PATCH http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/combos/{id}

Delete combo

bash

curl -X DELETE http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

删除组合

bash

curl -X DELETE http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/metrics

Get combo metrics

bash

curl http://localhost:20128/api/combos/metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

获取组合指标

bash

curl http://localhost:20128/api/combos/metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/test

Test a combo configuration

bash

curl -X POST http://localhost:20128/api/combos/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

测试组合配置

bash

curl -X POST http://localhost:20128/api/combos/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/fallback/chains

List fallback chains

Returns all registered fallback chains for model routing.

bash

curl http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

列出故障转移链

返回为模型路由注册的所有故障转移链。

bash

curl http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/fallback/chains

Create fallback chain

Registers a fallback routing chain for a model.

bash

curl -X POST http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

创建故障转移链

为模型注册一条故障转移路由链。

bash

curl -X POST http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/fallback/chains

Delete fallback chain

bash

curl -X DELETE http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

删除故障转移链

bash

curl -X DELETE http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/auto

GET combos › auto

bash

curl http://localhost:20128/api/combos/auto \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET combos › auto（自动组合）

bash

curl http://localhost:20128/api/combos/auto \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/builder/options

GET combos › builder › options

bash

curl http://localhost:20128/api/combos/builder/options \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET combos › builder › options（构建器选项）

bash

curl http://localhost:20128/api/combos/builder/options \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/duplicate

POST combos › duplicate

bash

curl -X POST http://localhost:20128/api/combos/duplicate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST combos › duplicate（复制组合）

bash

curl -X POST http://localhost:20128/api/combos/duplicate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/combos/reorder

POST combos › reorder

bash

curl -X POST http://localhost:20128/api/combos/reorder \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST combos › reorder（重新排序）

bash

curl -X POST http://localhost:20128/api/combos/reorder \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Payloads

请求载荷

See the full OpenAPI specification at

GET /api/openapi/spec

docs/openapi.yaml

for detailed request/response schemas.

有关详细的请求和响应 Schema，请参阅完整的 OpenAPI 规范：

GET /api/openapi/spec

或

docs/openapi.yaml

。

OmniRoute — Routing & Combos

OmniRoute — 路由与组合

Requires

OMNIROUTE_URL

and

OMNIROUTE_KEY

. See entry-point SKILL for setup.

需要配置

OMNIROUTE_URL

和

OMNIROUTE_KEY

。有关设置说明，请参阅入口点 SKILL。

What is a combo?

什么是组合？

A combo is a named group of providers/models with a routing strategy. All requests through a combo are automatically distributed, failed-over, and load-balanced — the caller uses a single model ID like

my-combo

组合（combo）是一组具有路由策略的具名提供商/模型。通过组合发出的所有请求都会自动进行分发、故障转移和负载均衡，调用方只需使用一个模型 ID，例如

my-combo

。

List existing combos

列出已有组合

bash

curl $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

Response includes

id

name

strategy

enabled

, and per-target stats.

bash

curl $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

响应包含

id

、

name

、

strategy

、

enabled

以及各目标的统计信息。

Create a combo

创建组合

bash

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-combo",
    "strategy": "priority",
    "targets": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
    ]
  }'

bash

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-combo",
    "strategy": "priority",
    "targets": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
    ]
  }'

19 public routing strategies

19 种公开路由策略

Strategy	Description
`priority`	Always use target[0]; fall back on error
`weighted`	Distribute by weight percentage
`round-robin`	Rotate targets in order
`context-relay`	Chain models for very long contexts
`fill-first`	Fill quota of target[0] before spilling
`p2c`	Power-of-two choices: sample two targets, pick the better candidate
`random`	Uniform random selection
`least-used`	Route to the target with the lowest observed usage
`cost-optimized`	Pick the cheapest eligible target for the token estimate
`reset-aware`	Prefer targets based on quota-reset state
`reset-window`	Order targets by their configured reset window
`headroom`	Prefer targets with more remaining quota headroom
`strict-random`	Random without repeating until all targets have been used
`auto`	Auto-Combo scoring across 16 factors
`lkgp`	Last-known-good-provider sticky routing
`context-optimized`	Pick the best model for the request's context size
`cache-optimized`	Prefer targets with stronger cache affinity
`fusion`	Run a panel in parallel and synthesize one judged response
`pipeline`	Run a configured sequence of targets as a pipeline

策略	描述
`priority`	始终使用 target[0]；发生错误时回退
`weighted`	按权重百分比分配请求
`round-robin`	按顺序轮换目标
`context-relay`	为超长上下文串联模型
`fill-first`	先填满 target[0] 的配额，再溢出到其他目标
`p2c`	Power-of-Two Choices：抽取两个目标，选择更优候选
`random`	均匀随机选择
`least-used`	路由到观测使用量最低的目标
`cost-optimized`	根据 token 估算选择成本最低的符合条件目标
`reset-aware`	根据配额重置状态偏好目标
`reset-window`	根据配置的重置窗口对目标排序
`headroom`	优先选择剩余配额余量更大的目标
`strict-random`	随机选择，在所有目标均使用前不重复
`auto`	基于 16 个因素进行 Auto-Combo 评分
`lkgp`	Last-Known-Good-Provider 粘性路由
`context-optimized`	根据请求的上下文大小选择最佳模型
`cache-optimized`	优先选择缓存亲和性更强的目标
`fusion`	并行运行模型面板并综合生成一个经评审的响应
`pipeline`	按流水线顺序运行一组目标

Auto-combo (recommended for production)

Auto-Combo（建议用于生产环境）

Auto-combo scores each candidate on 16 factors every request:

bash

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-auto",
    "strategy": "auto",
    "targets": [
      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
      { "provider": "openai",    "model": "gpt-4o-mini" },
      { "provider": "google",    "model": "gemini-2.0-flash" }
    ]
  }'

Then call it with:

bash

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'

Auto-Combo 每次请求都会根据 16 个因素对每个候选项进行评分：

bash

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-auto",
    "strategy": "auto",
    "targets": [
      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
      { "provider": "openai",    "model": "gpt-4o-mini" },
      { "provider": "google",    "model": "gemini-2.0-flash" }
    ]
  }'

然后使用以下方式调用：

bash

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'

Activate / deactivate a combo

启用或禁用组合

bash

undefined

bash

undefined

Activate

curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle
-H "Authorization: Bearer $OMNIROUTE_KEY"
-d '{ "enabled": true }'

undefined

curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle
-H "Authorization: Bearer $OMNIROUTE_KEY"
-d '{ "enabled": true }'

undefined

Get combo metrics

获取组合指标

bash

curl $OMNIROUTE_URL/api/combos/{id}/metrics \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

Returns p50/p95/p99 latency, success rate, cost, and per-target breakdown.

bash

curl $OMNIROUTE_URL/api/combos/{id}/metrics \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

返回 p50/p95/p99 延迟、成功率、成本以及各目标的明细数据。

Simulate routing (dry run)

模拟路由（试运行）

bash

curl -X POST $OMNIROUTE_URL/api/routing/simulate \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'

Returns which provider would be selected and why — no actual API call is made.

bash

curl -X POST $OMNIROUTE_URL/api/routing/simulate \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'

返回将选择的提供商及其原因，不会实际发起 API 调用。

Via MCP (if OmniRoute is your MCP server)

通过 MCP 使用（如果 OmniRoute 是你的 MCP 服务器）

omniroute_list_combos     → list all combos
omniroute_switch_combo    → enable/disable a combo
omniroute_set_routing_strategy → change strategy at runtime
omniroute_simulate_route  → dry-run routing decision
omniroute_best_combo_for_task → get recommendation by task type

omniroute_list_combos     → 列出所有组合
omniroute_switch_combo    → 启用或禁用组合
omniroute_set_routing_strategy → 在运行时更改策略
omniroute_simulate_route  → 试运行路由决策
omniroute_best_combo_for_task → 根据任务类型获取推荐

Errors

错误

```
404 combo not found
```
→ check
```
id
```
from
```
/api/combos
```
```
400 invalid strategy
```
→ use one of the 19 strategies above
```
409 name conflict
```
→ combo name already exists

```
404 combo not found
```
→ 检查
```
/api/combos
```
中的
```
id
```
```
400 invalid strategy
```
→ 使用上述 19 种策略之一
```
409 name conflict
```
→ 组合名称已存在