> ## 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 原生功能可能不可用。
* 切換目標模型可能導致供應商側提示詞快取無法複用。
* 生產環境輪換路由憑證時，應先通過狀態介面停用舊路由，再執行刪除。

控制台操作流程和整合連結請參閱[智慧路由](/zh-hant/api-reference/smart-routing)。