> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能路由 API

> 通过 API 创建智能路由 Key、配置模型层级、发起推理并查询统计。

## 概述

智能路由会根据请求复杂度，从配置的模型池中自动选择模型。在系统 API 中，路由表现为一条设置了 `smart_routing: true` 的 API Key 记录；创建、更新、启停、显示 Key 和删除操作都复用普通 Key 的 `/api/token/` 接口。

| 控制台名称   | API 字段    | 用途          |
| ------- | --------- | ----------- |
| Simple  | `simple`  | 速度快、成本较低的请求 |
| Complex | `complex` | 更复杂的任务      |
| Ultra   | `super`   | 最高能力的价格基准层级 |

存储的层级对象还包含 `reasoning`。当前控制台会将它设置为与 `simple` 相同的模型，以保持兼容。

<Warning>
  `smart_route_tiers` 是经过 JSON 编码的字符串，不能直接发送为嵌套 JSON 对象。
</Warning>

## 读取当前预设

预设模型 ID 属于部署配置。请从 `/api/status` 动态读取，不要从截图复制模型名称：

```bash theme={null}
status_response=$(curl -fsS "$BASE_URL/api/status")

jq -e '
  .success == true
  and .data.smart_routing_enabled == true
  and (.data.smart_routing_model_aliases | index("auto") != null)
' <<< "$status_response" >/dev/null

presets=$(jq -er '.data.smart_routing_presets | fromjson' \
  <<< "$status_response")

jq '.' <<< "$presets"
```

如果智能路由未启用，或 `auto` 未出现在路由别名列表中，第一个检查会终止流程。

选择一个预设并补齐兼容字段：

```bash theme={null}
tiers=$(jq -ce '
  .[0].pools
  | .reasoning = .simple
  | {simple, reasoning, complex, super}
  | select(all(.[]; type == "string" and length > 0))
' <<< "$presets")
```

创建前应确认三个有效层级都设置了模型，并且模型对所选分组可用。还要与 `.data.smart_routing_excluded_models` 进行不区分大小写的比较；不能选择被排除的模型。

## 创建智能路由 Key

```bash theme={null}
name="smart-route-$(date +%s)-$RANDOM"

payload=$(jq -n \
  --arg name "$name" \
  --arg tiers "$tiers" '{
    name: $name,
    expired_time: -1,
    remain_quota: 0,
    unlimited_quota: true,
    model_limits_enabled: false,
    model_limits: "",
    allow_ips: "",
    group: "default",
    cross_group_retry: false,
    smart_routing: true,
    smart_route_tiers: $tiers
  }')

curl -fsS -X POST "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq
```

创建响应不返回 ID。搜索时设置 `exclude_smart_routing=false` 才能定位路由记录：

```bash theme={null}
route=$(curl -fsS --get "$BASE_URL/api/token/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "keyword=$name" \
  --data-urlencode "exclude_smart_routing=false" \
  --data-urlencode "p=1" \
  --data-urlencode "size=10")

route_id=$(jq -er --arg name "$name" '
  [.data.items[]
    | select(.name == $name and .smart_routing == true)]
  | if length == 1 then .[0].id
    else error("expected exactly one matching Smart Routing key")
    end
' <<< "$route")
```

## 更新模型池

先读取当前记录，再修改解码后的层级配置。更新请求体必须保留其他全部可变字段。

```bash theme={null}
current=$(curl -fsS "$BASE_URL/api/token/$route_id" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

new_tiers=$(jq -cer '
  .data.smart_route_tiers
  | fromjson
  | .complex = "YOUR_COMPLEX_MODEL"
  | .reasoning = .simple
' <<< "$current")

update_payload=$(jq --arg tiers "$new_tiers" '.data | {
  id,
  name,
  expired_time,
  remain_quota,
  unlimited_quota,
  model_limits_enabled,
  model_limits,
  allow_ips,
  group,
  cross_group_retry,
  smart_routing,
  smart_route_tiers
} | .smart_routing = true | .smart_route_tiers = $tiers' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$update_payload" | jq
```

保存后的配置会对后续路由请求生效。

## 显示并使用路由 Key

```bash theme={null}
stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/$route_id/key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -er '.data.key')

route_api_key="sk-${stored_key#sk-}"
```

调用推理端点时，将 `model` 设置为 `auto`：

```bash theme={null}
curl -fsS https://api.mixroute.ai/v1/chat/completions \
  -H "Authorization: Bearer $route_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role":"user","content":"请总结这个系统架构的主要权衡。"}
    ]
  }' | jq
```

不要把系统访问令牌发送到推理端点。

## 路由统计

读取所有智能路由 Key 的汇总统计：

```bash theme={null}
curl -fsS "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

按 Key 和 Unix 秒级时间范围筛选：

```bash theme={null}
curl -fsS --get "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "token_id=$route_id" \
  --data-urlencode "start=START_UNIX_SECONDS" \
  --data-urlencode "end=END_UNIX_SECONDS" | jq
```

响应包含 `requests`、`actual_quota`、`saved_quota`、带有 `baseline` 和 `actual` 的 `daily` 明细、`tier_dist` 以及 `trial_start_ts`。

试用期和服务费比例也应从 `/api/status` 动态读取：

```bash theme={null}
curl -fsS "$BASE_URL/api/status" | jq '{
  trial_days: .data.smart_routing_free_trial_days,
  service_fee_percent: .data.smart_routing_service_fee_percent
}'
```

## 使用限制

* 请求使用 OpenAI 兼容的 `/v1/chat/completions` 格式。
* 路由到 Claude 模型时使用 OpenAI 兼容模式，部分 Claude 原生功能可能不可用。
* 切换目标模型可能导致供应商侧提示词缓存无法复用。
* 生产环境轮换路由凭证时，应先通过状态接口停用旧路由，再执行删除。

控制台操作流程和集成链接请参阅[智能路由](/cn/smart-routing)。