同一个模型可能有多个服务商通道。Token Market 会先根据模型能力、工作空间权限和当前通道状态建立可用候选集,再由智能路由自动选择通道。本文介绍 API 调用时的路由配置;模型详情页上方的服务商数据查看、筛选和表格排序请参考下方第 3 节。
Token Market 的 API 示例默认使用“自动”路由。不指定固定服务商时,网关会在当前可用通道中综合处理能力、价格、延迟、吞吐和可靠性,并在请求失败时按可用候选继续路由。实际可选字段和筛选项会根据模型类型、计费方式及实时数据动态变化。
如果业务对调用条件有明确要求,可以进入模型详情页底部的“统一 API Endpoint 与代码示例”区域配置路由条件。页面只展示当前模型支持的控件,常见包括:
选择条件后,页面会同步更新可复制的 API 示例。OpenAI 兼容请求会将服务商路由条件写入 extra_body.provider,例如:
{
"model": "<MODEL_ID>",
"extra_body": {
"provider": {
"only": ["<PROVIDER>"],
"ignore": [],
"sort": ["latency", "output_price"],
"latency_range": [0, 2],
"allow_fallbacks": false
}
}
}
only=[]、ignore=[] 和 order=[] 合法并等价于未设置;范围条件必须恰好包含两个非负值,且下界不能大于上界,range=[] 非法。不同模型使用的价格维度、长度限制和指标并不相同,请以页面当前生成的请求示例及实际显示单位为准。
建议先在模型详情页生成示例请求,再复制最终代码;不要手工臆测不存在的路由字段。
价格、延迟、吞吐和可靠性会随模型、服务商、时间窗口和请求条件变化。生产环境请设置超时、有限重试和必要的降级策略,并结合请求日志验证真实路由结果。指标口径请参考性能指标。
通过 API 显式设置路由时,请使用 extra_body.provider;模型 ID 只填写真实的模型 ID,不要把路由条件拼进模型 ID。字段用法和回退规则见下方第 2 节。
所有公开 API 的路由条件统一使用 extra_body.provider。OpenAI 兼容 JSON 请求将其作为 extra_body 中的对象传入;OpenAI Python SDK 使用 extra_body={"provider": {...}},multipart 请求则将 extra_body 作为 JSON 字符串表单字段。
extra_body={"provider": {"sort": ["latency"]}}
核心字段和处理方式如下:
| 字段 | 示例 | 作用 |
|---|---|---|
sort | ["latency", "output_price"] | 按延迟、吞吐、输入/输出价格或支持的输入长度对候选通道排序。 |
| 指标范围 | latency_range: [0, 2] | 按指标限制候选通道;范围必须恰好包含两个非负值,且下界不能大于上界。 |
order | ["<PROVIDER>"] | 在最后提升数组中指定的 provider。 |
常用排序策略包括:
latency:延迟优先,适合交互式请求;throughput:吞吐优先,适合并发或批量任务;input_price / output_price:输入或输出价格优先,适合成本敏感的任务;input_length:输入长度优先,适合长上下文请求。服务商范围与回退参数如下:
| 参数 | 示例 | 说明 |
|---|---|---|
only | ["<PROVIDER_A>", "<PROVIDER_B>"] | 仅在指定的服务商集合中选择。 |
ignore | ["<PROVIDER>"] | 从候选集合中排除指定服务商;不会因回退而放宽。 |
| 指标范围 | "latency_range": [0, 2] | 范围条件必须使用两个非负值;价格单位为 USD / 百万 tokens,延迟单位为秒,吞吐单位为 tokens/s。 |
order | ["<PROVIDER>"] | 在最后提升指定服务商的顺序。 |
allow_fallbacks | false | 控制首选条件没有匹配通道时是否放宽部分条件并回退。 |
完整请求示例:
curl "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_ID>",
"messages": [{"role": "user", "content": "Hello"}],
"extra_body": {
"provider": {
"only": ["<PROVIDER>"],
"ignore": [],
"sort": ["latency"],
"latency_range": [0, 2],
"allow_fallbacks": false
}
}
}'
用户控制条件按 ignore → ranges → only → sort → order 顺序处理;order 在最后提升指定 provider。非空 only 默认 allow_fallbacks=false,未指定服务商范围时默认 true。设为 false 时只在 only 和各项范围形成的候选集合内路由;设为 true 且首选集合为空时,可以放宽 only、范围、sort 和 order,但不会放宽 ignore、模型访问权限、端点能力或通道可用性。only 与 ignore 不能重叠。校验失败返回 HTTP 400,错误码为 invalid_request;最终没有可用通道时返回 HTTP 503,错误码为 no_available_provider。
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。
无可用通道: 如果所有候选服务商都无法满足硬性过滤条件(例如
latency_range),网关返回 HTTP 503,错误码固定为no_available_provider。
在模型详情页上方,您也可以根据需求筛选匹配的服务商,并按照指标排序(点击表格第一行的指标文字,如“吞吐”)。默认按照输出吞吐从高到低排序。服务商表格的价格以当前账号最终看到并使用的价格区间为准;API 路由中的价格筛选和排序使用 USD / 百万 tokens 的基础单价。价格、延迟、吞吐和可靠性会随模型、服务商与时间变化。