跳转到主要内容
在模型 ID 前加上提供商 ID 和一个冒号,例如 baseten:thinking-machines/inkling-small,请求就只会在该提供商上运行,不会回退到其他提供商。 格式为 <provider-id>:<canonical-model-id>。第一个冒号用来分隔提供商;模型命名空间之后的冒号仍属于模型 ID。在 google-ai-studio:google/gemma-4-26b-a4b:free 中,提供商是 google-ai-studio,模型是 google/gemma-4-26b-a4b:free。 如果你只是偏好某个提供商,并希望它失败时回退,请改用普通模型 ID 配合路由与回退控制。

发送请求

在端点接受模型 ID 的任何地方都可以使用限定 ID。

提供商仍需通过的检查

限定符只是把路由范围缩小到一个提供商,不会跳过任何其他检查。该提供商仍必须:
  • 在所请求的端点上提供该规范模型,并已启用相应能力
  • 满足工作区、API 密钥、预设和隐私方面的限制
  • 支持所请求的服务层级和参数
  • 已配置价格
任何一项检查失败,请求都会被拒绝。Phaseo 永远不会悄悄改选其他提供商。

与 provider 或 routing 字段组合使用

限定符与任何显式路由字段必须一致。匹配的 provider.only 或 routing.only 会被接受:
如果允许列表指定了其他提供商,或忽略列表中包含被限定的提供商,请求会被拒绝,返回 provider_qualified_model_conflict:

在某个提供商上请求免费路由

只有当该提供商对此模型和端点有符合条件的免费路由时,限定的 :free 模型才会被接受。规范的 :free 模型并不意味着底层模型的每个提供商都免费提供它。
该路由的价格卡不能为空,并且其上当前的每条定价规则都必须标记为 free,价格恰好为零。价格缺失、收费、混合或为负,或者存在价格为零但未标记 free 的规则,请求都会在到达提供商之前被拒绝。

提供商 ID 和别名

使用 Phaseo 提供商目录中的提供商 ID(参见 API 提供商)。ID 会被转为小写,已知的旧版或品牌别名会映射到规范 ID:NovitaAI 和 novita-ai 都会变成 novita。格式错误和未知的 ID 会在选择提供商之前被拒绝;它们永远不会作为模型名称的一部分发送到上游。

验证错误

错误的限定 ID 会返回 HTTP 400,错误代码为 validation_error。reason 和 details[].keyword 给出原因:
其他错误格式请参见错误与调试。
最后修改于 2026年11月5日