模型发现

使用模型页面或模型 API 查看可用的文本模型。模型元数据包括厂商、服务提供商、模态、上下文长度、支持的 API 系列、支持的能力、可用性、账户级限制和积分定价。

端点： GET /v1/models 用途： 列出当前账户可用的模型。

复制curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

能力矩阵

API 系列兼容性矩阵

认证

每个 API 请求都使用 bearer token。请将密钥存储在服务器端环境变量中，团队访问变更时及时轮换，并记录请求 ID 以便调试。

密钥安全建议

1. 将 API 密钥保留在服务器端。切勿在浏览器或移动客户端代码中暴露密钥。
2. 为开发、预发布、生产和第三方集成使用不同的密钥。
3. 在可用时按环境、服务、客户或租户限定密钥范围。
4. 在员工离职、供应商访问变更或疑似泄露后轮换密钥。
5. 将密钥存储在密钥管理器或环境变量中，而非源代码中。

控制台使用

BasicRouter 控制台是 API 访问、模型可用性、路由策略、用量可见性和计费管理的运维控制面板。它为账户管理员提供密钥、模型、请求、积分和生产模型流量账户级控制的集中视图。

管理 API 密钥

在控制台中创建、轮换、吊销和标记 API 密钥。为开发、预发布、生产和各个服务使用不同的密钥，以便按环境或应用审计和隔离用量。

模型列表

使用模型页面查看账户可用的模型。每个模型条目可能包括厂商、服务提供商、模态、支持的 API 系列、上下文长度、能力标志、可用性状态和定价信息。

对于生产应用，启用流量前请验证模型能力。部分参数和功能取决于模型，可能并非在所有 API 系列中都受支持。

用量与日志

用量与日志视图提供 API 流量的运维可见性。团队可以检查请求量、所选模型、解析的路由目标、积分消耗、延迟、错误码和请求 ID。

• 排查失败的请求。
• 识别高成本工作负载。
• 比较不同应用和环境之间的模型用量。
• 验证路由和兜底行为。
• 调查延迟或提供商可用性问题。
• 联系支持时提供请求 ID。

每个 API 响应包含或暴露一个 BasicRouter 请求 ID。请将此 ID 存储在应用日志中，以提高生产调试和支持升级的效率。

兜底

兜底是 BasicRouter 的弹性机制。当主模型或路由策略失败时，系统自动切换到备用模型以继续处理请求。这使你的应用保持响应能力，并最大限度地降低服务中断的风险。

为什么兜底很重要

在生产环境中，模型服务可能会遇到许多不可预测的问题：

• 模型服务故障：上游 API 暂时不可用或超时。
• 性能波动：模型高负载导致响应缓慢或失败。
• 路由失败：智能路由选择的所有候选模型均不可用。

兜底通过提供可靠的备用路径来保持应用的可用性。

核心优势

全局兜底模型配置

BasicRouter 支持从控制台后端设置全局兜底模型。所有请求在失败时自动使用此模型作为备用。

配置方法：

1. 前往 BasicRouter 策略设置页面。
2. 找到 默认兜底模型 设置。
3. 从下拉列表中选择你的全局兜底模型。
4. 保存设置以立即生效。

全局配置的优势：

• 无需修改代码：配置一次即全局生效，无需在每个请求上重复设置。
• 集中管理：在一个位置管理兜底策略，便于调整和监控。
• 简化维护：降低代码复杂度和配置出错的可能性。
• 灵活覆盖：请求级兜底配置优先级更高，可为特定场景覆盖全局设置。

请求级兜底配置

对于特定业务场景，可在单个请求上指定兜底模型以覆盖全局配置。

使用 router.fallBackModels 参数指定兜底模型：

复制{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

优先级规则

当存在多个兜底配置时，优先级从高到低为：

1. 请求级 router.fallBackModels：在单个请求上指定的兜底模型。
2. 全局默认兜底模型：在控制台配置的全局兜底模型。
3. 无兜底：如果两者都未配置，请求失败时返回错误。

账户管理

根据账户类型，控制台可能包括账户级模型启用、经销商或分销商控制、计费配置和访问设置。管理员可使用这些控制项，使模型访问、用量可见性和计费责任与应用、客户账户或业务单元保持一致。

生产运维检查清单

计费与积分

BasicRouter 在文本、图像、视频和其他支持的模型工作负载中采用基于积分的计费模型。积分为多模型和多提供商用量提供统一单位，使团队能够跨模态和 API 系列一致地管理消耗。

详细的模型定价可在模型页面或通过模型元数据 API 获取。定价可能因模型、提供商、模态、分辨率、token 类型、输出长度、任务时长、账户类型和商业协议而异。

充值与钱包

账户可添加按量付费钱包积分以获得灵活用量。除非账户适用自定义计费规则，否则钱包积分在月度套餐积分和资源包消耗完毕后使用。

除非适用商业条款另有规定，钱包积分不会过期。充值按量付费钱包时会收取服务费。

月度套餐和资源包

每个用户或账户可选择一个有效的月度套餐。月度套餐在计费周期内提供约定数量的用量容量、商业条款和账户级访问配置。

用户还可购买多个资源包以获得额外用量容量。资源包可将承诺用量与按量付费钱包余额分开，适用于大批量文本、图像、视频或专用工作负载用量。

扣费顺序

除非配置了自定义计费规则，否则积分按以下顺序扣减：

对于有自定义商业条款的账户，扣费顺序、过期规则、包含用量和定价可能不同。账户特定规则会显示在控制台或通过商业协议提供。

自定义定价

可为每个用户或账户自定义定价。企业客户、经销商账户、分销商账户和大批量客户可能符合自定义定价条件。请联系销售获取报价。

自定义定价可按账户、模型、提供商、模态、区域、用量或商业协议配置。启用自定义定价后，控制台和计费 API 会在可用时反映账户特定的定价和扣减规则。

计价单位

不同模型模态使用不同的计量单位。BasicRouter 根据模型定价规则将这些单位转换为积分。

计价单位可能因模型而异。在生产环境中启用模型前，请务必参考模型详情页面或定价元数据。

用量归因

BasicRouter 用量可按账户、API 密钥、模型、模态或时间范围查看。这使团队能够将成本归因到应用、环境、客户或内部业务单元。

积分余额

查看账户可用的积分数量。余额分为三个按顺序扣减的钱包：月度套餐积分、购买的资源包和按量付费钱包。还提供一个合并资源总量（月度套餐 + 资源包，不含按量付费），用于将包含用量与充值消费分开跟踪。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/billing/balance。

用量详情

查看分页的、按时间顺序排列的用量记录列表，用于报告、监控和内部成本分摊。每条记录显示模型、模型类型（文本、图像或视频）、扣减的积分，以及每次扣减来自哪个钱包的明细。结果可筛选到特定时间范围。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/usage。

交易记录

使用交易记录查看积分变动，包括充值、套餐分配、资源包发放、用量扣减、调整和管理修正。

以编程方式获取此信息，请参见 API 参考中的 GET /v1/billing/transactions。

失败请求与退款

校验错误、认证错误和权限错误通常不计费，因为未发生模型执行。到达上游模型或生成部分输出的请求可能会消耗积分，具体取决于模型、提供商和响应状态。

对于异步图像和视频任务，计费行为取决于任务是已接受、已开始、已完成、已失败还是已取消。任务详情响应在消耗积分时会包含用量信息。

充值、月度套餐、资源包和已消耗的积分不可退款，除非适用商业协议另有规定或法律要求。

运维

错误处理

BasicRouter 返回稳定的错误码，便于应用统一处理重试、兜底、计费问题和调试。

兼容上游的端点会尽量保留原始 API 系列的错误结构。BasicRouter 原生端点使用 BasicRouter 错误对象。

HTTP 状态码与错误码映射

常见错误码