CC Switch 接入、线路探活与余额查询

RootFlowAI 账户中心可以把 API Key、余额查询和备用线路一次导入 CC Switch，无需另外生成系统访问令牌或填写用户 UID。

不使用 CC Switch 也可以通过本文的 HTTP 接口和 Python 脚本查询账户余额，适用于其他桌面客户端、个人脚本和服务端集成。

一键导入

1. 登录 RootFlowAI 账户中心。
2. 找到需要使用的 API Key，点击「导入 CC Switch」。
3. 选择应用、主线路和名称。
4. 点击「打开 CC Switch」，在客户端确认导入。

导入内容包括：

• 当前模型 API Key。
• 应用的默认主模型：Claude 使用 claude-opus-5，Codex 使用 gpt-6-astra，OpenCode 使用 gpt-5.6-sol，Gemini 使用 gemini-3.7-flash。
• 用户选中的主线路。
• 其余 RootFlowAI 备用线路。
• 每 5 分钟自动刷新的账户余额查询。

余额查询使用同一个模型 API Key，不保存门户登录状态，也不会发起模型请求或产生模型推理费用。

线路探活与测速

CC Switch 会把选中的线路作为主线路，其余线路作为测速候选。Codex 和 OpenCode 自动使用各线路的 /v1 地址。

线路测试表示目标地址能够返回 HTTP 响应，用于判断网络可达性和延迟；它不代表特定模型一定可用。余额查询成功可以验证 API Key 当前有效，但不验证该 Key 的模型权限。

不使用 CC Switch 时如何探活

可以向对应线路的 /api/status 发送不带 Key 的 GET 请求：

以主线路为例：

curl --silent --show-error --fail \
  --connect-timeout 5 --max-time 10 \
  --write-out '\nHTTP %{http_code}; total %{time_total}s\n' \
  https://api.rootflowai.com/api/status

预期为 HTTP 200，JSON 中的 success 为 true。time_total 是本次 HTTP 请求总耗时，包含连接与服务响应，并非模型首字延迟或生成速度。替换域名即可检查其他线路。

探活地址不需要追加 /v1，也不要用登录页、/v1/chat/completions 或 /v1/responses 代替探活。探活成功不代表某个模型或上游渠道一定可用。自行设置定时探活时建议至少间隔 60 秒，失败后退避重试。

CC Switch 余额检查脚本

新导入的 Provider 会自动携带余额配置。已有 Provider 可以打开「配置用量查询」，启用查询并选择「自定义」，填写：

将下面的完整脚本填入「提取器代码」，点击「测试脚本」，成功后保存配置：

({
  request: {
    url: "{{baseUrl}}/api/integrations/usage",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "Accept": "application/json"
    }
  },
  extractor: function(response) {
    if (response.success && response.data) {
      return response.data;
    }
    return {
      isValid: false,
      invalidMessage: response.message || "用量查询失败"
    };
  }
})

{{baseUrl}} 和 {{apiKey}} 由 CC Switch 替换，保留占位符即可。这里的请求地址是门户域名 https://rootflowai.com，与模型请求使用的主线路、香港线路、美国线路地址不同。不要在请求地址后追加 /v1。

其他客户端与脚本查询余额

HTTP 接口

GET https://rootflowai.com/api/integrations/usage
Authorization: Bearer <你的 RootFlowAI 模型 API Key>
Accept: application/json

• 使用账户中心创建的模型 API Key，包含 sk- 前缀。无需系统访问令牌、用户 UID、Cookie 或门户登录状态。
• 只支持 GET；不要附加查询参数或请求体，也不要使用 HEAD。
• Key 仅通过 Authorization 请求头传递，不要放在 URL 中。
• 所有模型线路共用这个余额地址，不能将其域名替换成 api.rootflowai.com、hk.rootflowai.com 或 us.rootflowai.com。
• 查询成功不调用模型、不消耗模型推理额度。建议每 5 分钟查询一次，无需每次模型调用后都查询。
• 接口不提供浏览器跨域访问（CORS）。其他客户端应从桌面应用、本地脚本或自己的服务端发起请求；不要把 Key 写进公开网页代码。

curl 示例

下面的 Bash 示例交互读取 Key，不会把 Key 明文写入命令历史。运行时不要启用 set -x 或将带鉴权的请求输出到日志。

read -r -s -p 'RootFlowAI API Key: ' ROOTFLOWAI_API_KEY
printf '\n'
export ROOTFLOWAI_API_KEY

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 15 \
  --header "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  --header 'Accept: application/json' \
  https://rootflowai.com/api/integrations/usage

unset ROOTFLOWAI_API_KEY

Python 示例

下面的 Python 3 脚本仅使用标准库。它优先读取环境变量 ROOTFLOWAI_API_KEY，没有配置时会交互输入；每次运行只查询一次余额。

import getpass
import json
import os
import sys
import urllib.error
import urllib.request

key = os.environ.get("ROOTFLOWAI_API_KEY") or getpass.getpass("RootFlowAI API Key: ")
if not key.strip():
    sys.exit("API Key is required")

request = urllib.request.Request(
    "https://rootflowai.com/api/integrations/usage",
    headers={"Authorization": f"Bearer {key}", "Accept": "application/json"},
    method="GET",
)

try:
    with urllib.request.urlopen(request, timeout=15) as response:
        payload = json.load(response)
    if payload.get("success") is not True:
        sys.exit("Balance query failed")
    data = payload["data"]
    print(f"Remaining: {data['remaining']} {data['unit']}")
    print(f"Used: {data['used']} {data['unit']}")
    print(f"Total: {data['total']} {data['unit']}")
except urllib.error.HTTPError as error:
    print(f"Balance query failed: HTTP {error.code}", file=sys.stderr)
    if error.code == 429:
        print(f"Retry after {error.headers.get('Retry-After', '60')} seconds", file=sys.stderr)
    sys.exit(1)
except (urllib.error.URLError, TimeoutError):
    sys.exit("Network error or timeout; retry later")
except (ValueError, KeyError, TypeError):
    sys.exit("Unexpected balance response")

服务端集成时，通过部署环境或密钥管理工具注入 ROOTFLOWAI_API_KEY。不要将真实 Key 写入脚本、仓库、工单或监控标签。

返回数据与余额口径

成功响应示例，以下金额仅为演示：

{
  "success": true,
  "data": {
    "planName": "RootFlowAI",
    "remaining": 12.5,
    "used": 2.5,
    "total": 15,
    "unit": "USD"
  }
}

金额向下保留两位小数；各字段分别换算，展示值相加可能有 0.01 USD 的尾差。响应带有 Cache-Control: no-store，集成时不要缓存并持续展示为实时余额。

返回的是账户额度，不是单个 API Key 的独立限额。即使 Key 配置为无限额度，也能查询账户余额；有限额 Key 还需保有可用额度。Key 的模型权限仍以账户中心配置为准。

错误处理与查询频率

错误响应通常包含 success: false 和 message；网络故障或中间代理异常也可能返回非 JSON 内容，应先判断 HTTP 状态再解析数据。不要将查询失败视为余额为零。

同一个 Key 的应用层限制为每分钟 12 次，此外还有按出口 IP 和全局执行的限流；共享出口或并发请求可能更早收到 429。推荐间隔 5 分钟，遇到 429 遵守 Retry-After，其他临时故障也应退避，避免立即循环重试。

常见问题

导入后没有余额查询

请升级到支持 deep link 用量配置的 CC Switch 新版本，然后从账户中心重新导入 Provider；也可以按本文的「CC Switch 余额检查脚本」为已有 Provider 手动配置。

提示 API Key 无效或不可用

检查该 Key 是否已禁用、过期、删除或耗尽。设置了 IP 白名单的 Key 还需要允许当前网络出口地址。

余额暂时不可用

余额服务异常或请求过于频繁时，CC Switch 会保留 Provider 的模型配置。稍后刷新余额即可，不需要重新导入 API Key。

余额与账户中心短暂不一致

充值或消费后，余额数据可能有秒级同步延迟。CC Switch 默认每 5 分钟自动刷新，也可以手动刷新。核对时还需注意，接口返回的是整个账户的累计用量，而非单个 Key 或当天用量。

::: warning 安全提示 API Key 可以调用模型并查询余额。不要把导入链接、API Key 或 CC Switch 配置文件发送给他人。