智能路由

同一模型可能对应多个服务商通道。Token Market 先根据模型能力、工作空间权限和通道可用性建立候选集，再由默认策略选择通道。模型 ID、可用服务商、价格和部分能力以 Models API 与 Model Market 当前配置为准。

1. 使用 extra_body.provider 配置路由

所有公开接口统一把路由条件放在 extra_body.provider。原始 JSON 请求的最小示例如下：

{
  "model": "<MODEL_ID>",
  "extra_body": {
    "provider": {
      "only": ["<PROVIDER>"],
      "ignore": [],
      "sort": ["latency", "output_price"],
      "latency_range": [0, 2],
      "allow_fallbacks": false
    }
  }
}

OpenAI Python SDK 使用 extra_body={"provider": {...}}。multipart 请求将 extra_body 作为 JSON 字符串表单字段。不要把路由条件写入模型 ID。

2. 候选集、校验与回退

用户可控条件按 ignore → ranges → only → sort → order 处理；order 在最后提升指定 provider，而不是只在排序相同时才生效。

allow_fallbacks=false 时，只在 only 与各项 range 条件形成的候选集合内路由。allow_fallbacks=true 且首选集合为空时，可以放宽 only、range、sort 和 order；不会放宽 ignore、模型访问权限、端点能力或渠道可用性。非空 only 时默认 allow_fallbacks=false，否则默认 true。

每个 range 必须恰好包含两个非负值，且下界不能大于上界；range=[] 非法。only=[]、ignore=[] 和 order=[] 合法并等价于未设置。非空 only 与 ignore 不得重叠。校验失败返回 HTTP 400，错误码为 invalid_request；最终没有可用渠道时返回 HTTP 503，错误码为 no_available_provider。

3. 会话、价格与排查

Session ID 仅适用于 Chat Completions、Responses、Claude Messages、Gemini Generate Content 和 Stream Generate Content。读取顺序是顶层 session_id、extra_body.session_id、X-Session-Id，最长 256 个字符。它用于软粘性路由和上游缓存复用，只在当前请求仍允许且可用的通道中生效；默认有效期约 1 小时，成功使用后会续期。不同模型或无关会话应使用不同的 Session ID。

Models API 的 price.input_price_range 和 price.output_price_range 是基础 USD 价格范围，单位为 USD/百万 tokens。当前账号的用户可见价格范围 = 基础价格范围 × price.group_ratio；不进行人民币换算。路由的价格筛选、排序和比较使用基础 USD 单价。同一账号共享的 price.group_ratio 不改变服务商价格排序。

提供 X-Client-Request-Id 时，响应会原样回显该值；未提供时不会自动生成。响应通常包含 X-Upstream-Request-Id，用于网关请求追踪，并非供应商原始 request ID。建议保存这两个响应头和脱敏后的请求参数用于排查；如果请求未进入网关处理流程，网络层失败时不保证返回响应头。响应体中的 id 或 request_id 继续遵循各协议定义。