智能路由 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

路由统计

使用限制