MUSE

智能路由 ​

你只说要什么，中台决定交给谁做。

同一个模型档次背后通常挂着好几家服务商，它们的成功率、延迟、价格每天都在变。 智能路由就是那层调度：按最近 24 小时的真实战绩挑一家干活，挂了自动换下一家， 整个过程对你的调用代码透明——接口、参数、返回结构都不变。

接入方式：默认就开着 ​

不传 provider、不传 model（或者传 auto），你已经在用智能路由了：

bash
curl -X POST https://manager.museav.top/api/generate \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{"skill_slug":"ecom-white-backdrop","input":"米白色针织衫"}'

想控制一下"用哪一代模型"，就只传 model：

你传的含义建议
不传 / auto全交给路由✅ 默认这样
型号族名，如 gpt-image-2.5这一代随便哪家，该代所有上游参与轮换✅ 要稳定画风时用
具体渠道名，如 gpt-image-2.5-flare锁死一家⚠️ 那家挂了你就一起挂
provider: "xxx"点名服务商⚠️ 排障用，日常别传

视频同理，model 传对外档次名（如 Seedance 2.0）或 auto。 当前有哪些可选：GET /api/available-models（出图），?media_type=video（视频档次，带每档的时长上下限）。

锁死一家的代价

点名 provider 会绕过打分、绕过兜底链。那家临时抽风，你的请求就直接失败， 而不是被悄悄换到另一家做完。除非在排查具体某家的问题，否则不要传。

它替你做了四件事 ​

一、按战绩打分。 每家上游取最近 24 小时的真实任务样本算一个健康分：

权重看什么
45%成功率
25%人工分（我们对这家的综合评价）
20%延迟（P95 耗时 vs 该上游的软超时）
10%成本

最近 5 次里每有一次失败再额外扣分。新接入或刚恢复的上游没有战绩，按中性值起步， 先给流量把成功率测出来，不会被当成 0 分判死。

二、按质量分流量。 选中不是"永远挑最高分那家"，而是加权随机， 且权重是 分数 × 成功率²——平方是为了让质量差异真正落到流量上。 这条是实测调出来的：早期直接按分数分流时，一个成功率 42% 的上游拿到的流量 跟 85% 的那家几乎一样多，任务成功率长期卡在 87% 上不去。

掉队的上游仍保留一小股试探流量，它恢复了能自动爬回来——一刀切熔断会让它永远回不来。

三、失败自动换一家。 首选上游报错时：同一家最多试 2 次（仅限超时、限流这类瞬时错误）， 还不行就切兜底链的下一家，链走完才算任务失败。 任务状态里会留一条 上游生成失败，切换备用通道（1/2） 的记录，任务还在跑，不用你重发。

图片的兜底要求同一个模型：换了家又换了模型，出来的画风就是另一张图了， 那不是你要的东西。视频反过来——各家给同一个底模挂自己的别名，强求同名等于永远没有兜底， 所以视频允许换名，档次不变。

四、坏掉的自动摘除。 Key 失效、上游欠费会被自动摘出轮换，探活恢复后自动放回； 管理员也能手动停用某一家。两种停用都在选路前就过滤掉，不会让你撞上。

能力不够时会明确报错 ​

参考图、局部重绘（蒙版）、透明背景这些不是每家上游都支持。路由会先按能力筛候选， 一家都没有就返回 400 并说明原因，不会给你一张"看起来正常但不是你要的"的图：

json
{ "error": "透明背景需要支持 alpha 通道的上游，当前无可用上游——去掉 background=transparent 可以正常出图（白底）" }

看到这类 400 别重试，再打一万次也不会成，改参数或等我们接入支持的上游。 详见错误与限流。

你看不到上游是谁 ​

任务结果、用量统计都不下发服务商名字（/api/tenant-stats 自 2026-08-09 起不再返回 by_provider）。 这是有意的：谁在干活是中台的调度细节，今天这家明天那家， 你的系统不该依赖它——一旦依赖，我们换一家你就要跟着改代码。

想固定在某一代模型上？ ​

租户可以绑定模型，绑定后该租户的所有请求只在这一代里轮换，不用每次调用都传 model。 绑族名（gpt-image-2.5）而不是渠道名——绑渠道名会把同一代的其他几家全排除掉， 且不报错，属于那种"一直跑在次优通道上"的隐性损失。

需要配置绑定告诉我们。

接下来 ​