智慧路由 API

概述

智慧路由會根據請求複雜度，從設定的模型池中自動選擇模型。在系統 API 中，路由表現為一條設定了 smart_routing: true 的 API Key 記錄；建立、更新、啟停、顯示 Key 和刪除操作都複用一般 Key 的 /api/token/ 介面。

控制台名稱	API 欄位	用途
Simple	`simple`	速度快、成本較低的請求
Complex	`complex`	更復雜的任務
Ultra	`super`	最高能力的價格基準層級

儲存的層級物件還包含 reasoning。目前控制台會將它設定為與 simple 相同的模型，以保持相容。

smart_route_tiers 是經過 JSON 編碼的字串，不能直接傳送為巢狀 JSON 物件。

讀取目前預設

預設模型 ID 屬於部署設定。請從 /api/status 動態讀取，不要從截圖複製模型名稱：

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 未出現在路由別名列表中，第一個檢查會終止流程。選擇一個預設並補齊相容欄位：

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

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 才能定位路由記錄：

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")

更新模型池

先讀取目前記錄，再修改解碼後的層級設定。更新請求內容必須保留其他全部可變欄位。

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

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：

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 的彙總統計：

curl -fsS "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

按 Key 和 Unix 秒級時間範圍篩選：

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 動態讀取：

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

控制台操作流程和整合連結請參閱智慧路由。

當下熱門模型

OpenAI 官方庫使用

系統 API

文本系列

文本向量系列

圖像系列

視頻系列

其他

概述

讀取目前預設

建立智慧路由 Key

更新模型池

顯示並使用路由 Key

路由統計

使用限制

​概述

​讀取目前預設

​建立智慧路由 Key

​更新模型池

​顯示並使用路由 Key

​路由統計

​使用限制

概述

讀取目前預設

建立智慧路由 Key

更新模型池

顯示並使用路由 Key

路由統計

使用限制