API Probe - 多协议 API 测活工具

面向常见大模型接口的本地测活与兼容性诊断工具，支持简洁模式和专业模式。可配置协议、base URL、认证方式和请求体；非标准接口可通过专业模式测试。

功能亮点

• 支持 OpenAI Chat、OpenAI Responses、Anthropic、Gemini 及常见兼容接口。
• 同时提供本地图形界面、命令行和机器可读 JSON 输出。
• 可获取模型列表、批量测活、查询常见中转站余额与构造专业请求。
• API Key 不写入配置档案，错误结果自动脱敏；本地入口包含跨站、SSRF 和资源限制防护。
• 核心 CLI 和网页服务无 npm 运行时依赖，使用 Node.js 即可运行。

为什么选择 API Probe

| 能力 | API Probe | 常见单接口测试页 | |---|:---:|:---:| | OpenAI Chat / Responses | ✅ | 通常仅 Chat | | Anthropic / Gemini | ✅ | 通常不支持 | | 本地 UI + CLI + JSON | ✅ | 通常仅网页 | | 模型列表 / 批量测活 / 余额查询 | ✅ | 部分支持 | | 自定义 Method、Header、Body、解析路径 | ✅ | ❌ | | Key 不持久化、响应脱敏、重定向保护 | ✅ | 不一定 | | SSRF、跨站请求、请求体与并发限制 | ✅ | 不一定 |

适合排查“Key 是否有效”“Base URL 是否正确”“模型名是否存在”“中转站实现了哪种兼容协议”，也适合作为自动化脚本中的轻量诊断命令。

快速开始

直接下载

下载最新版完整 ZIP（仍需 Node.js 18+），解压后 Windows 可双击 启动.bat。启动器会通过 PowerShell 7 以 UTF-8 显示中文。

也可以不克隆仓库，直接通过 GitHub 运行：

npx --yes github:xydadada/api-probe --serve

npm 正式包也可直接运行：npx api-probe --serve。

方式一：图形界面（推荐）

1. 下载仓库，或运行 git clone https://github.com/xydadada/api-probe.git
2. 双击 启动.bat（需已安装 Node.js 和 PowerShell 7）
3. 自动打开浏览器 http://127.0.0.1:8765
4. 在简洁模式选预设或手动填 base url + key + 模型 → 点「测试调用」
5. 或切到专业模式构造自定义请求

macOS / Linux 或偏好终端的用户可运行：

git clone https://github.com/xydadada/api-probe.git
cd api-probe
npm start

浏览器会先把 API Key 发送给仅监听 127.0.0.1 的本地服务，再由本地服务转发到目标服务器。工具不会把 Key 写入服务端日志或结果文件。

方式二：命令行

# 列出所有预设
node api-probe.mjs --list

# 用预设测试（火山方舟 OpenAI 模式）
node api-probe.mjs --provider huoshan-openai --key sk-xxx

# 手动指定 base/key/协议
node api-probe.mjs --base https://api.deepseek.com --key sk-xxx --type openai-chat --model deepseek-chat

# 自动探测协议
node api-probe.mjs --base URL --key KEY --type auto --model MODEL

# 获取模型列表
node api-probe.mjs --models --base URL --key KEY

# 预设同样可用于模型列表和批量测试
node api-probe.mjs --models --provider openai --key KEY

# 查询余额/用量（New API / Sub2API / OpenAI Billing）
node api-probe.mjs --balance --base URL --key KEY

# 批量测试多个模型
node api-probe.mjs --batch --base URL --key KEY --batch-models "m1,m2,m3"

# New API 用户模型列表
node api-probe.mjs --user-models --base URL --key KEY

# 机器可读输出（适用于 list / models / balance / batch / user-models / 普通测试）
node api-probe.mjs --list --json

# 专业模式：自定义请求
node api-probe.mjs --pro-test --method POST --url "https://xxx/v1/chat/completions" --headers '{"Authorization":"Bearer {key}"}' --body '{"model":"{model}","messages":[]}' --key2 sk-xxx --model2 gpt-4o-mini

环境变量

CLI 支持 API_PROBE_BASE_URL、API_PROBE_API_KEY、API_PROBE_PROTOCOL 和 API_PROBE_MODEL，并兼容 OPENAI_BASE_URL / OPENAI_API_KEY 回退。优先级为：显式命令行参数 > --provider 预设 > API_PROBE_* > OPENAI_*。

$env:API_PROBE_BASE_URL = 'https://api.example.com/v1'
$env:API_PROBE_API_KEY = '<API_KEY>'
$env:API_PROBE_PROTOCOL = 'openai-chat'
$env:API_PROBE_MODEL = 'example-model'
node api-probe.mjs --json

环境变量可以避免把 Key 直接写进命令历史，但仍应使用短期或最小权限凭据，并避免将环境信息复制到公开日志。

支持的协议

| 协议 | 端点 | 认证 | |---|---|---| | OpenAI Chat | POST {base}/chat/completions | Authorization: Bearer <key> | | OpenAI Responses | POST {base}/responses | Authorization: Bearer <key> | | Anthropic | POST {base}/v1/messages | x-api-key: <key> + anthropic-version | | Gemini | POST {base}/models/{model}:generateContent | x-goog-api-key: <key> |

base URL 容错：OpenAI 兼容协议会尝试带/不带 /v1 的常见路径。auto 依次探测 OpenAI Chat、OpenAI Responses 和 Anthropic；Gemini 需明确选择。

余额/用量查询（中转站）

自动按顺序探测这些接口，解析余额字段：

| 平台 | 路径 | 字段 | |---|---|---| | New API | GET {base}/api/usage/token | total_granted/used/available/expires_at | | Sub2API | GET {base}/v1/usage | 同上 | | OpenAI Billing | GET {base}/dashboard/billing/credit_grants | 同上 | | New API 用户 | GET {base}/api/user/self | quota | | 站点状态 | GET {base}/api/status | price |

通用字段兼容：quota/balance/credit/credits（总额）、used/usage（已用）、remaining/available（剩余）、expires_at/expired_at（到期）。到期 Unix≤0 视为永不过期。

健康状态：healthy（正常）/ warning（超时）/ error（认证失败或网络错）/ unknown（未识别）。

内置预设（18 家，全部可编辑）

火山方舟×2、DeepSeek、OpenAI、OpenRouter、硅基流动、Moonshot、Anthropic、Gemini、智谱、通义千问、百川、阶跃星辰、MiniMax、零一万物、Groq、Together AI、Ollama。

接入任意第三方

编辑 providers.json，加一条记录即可，不用改代码：

{
  "id": "my-provider",
  "name": "我的第三方",
  "baseUrl": "https://my-api.example.com",
  "protocol": "openai-chat",
  "auth": { "type": "bearer" },
  "defaultModel": "my-model",
  "description": "我的自定义 provider"
}

auth.type 支持：

• bearer → Authorization: Bearer <key>
• x-api-key → x-api-key: <key>
• none → 无认证
• custom → 自定义头，需配 auth.headers：

  "auth": {
    "type": "custom",
    "headers": [ { "X-Custom-Key": "{key}" } ]
  }

配置档案（多组保存）

简洁模式顶部可保存/切换/删除配置档案（存 localStorage）。档案只保存协议、base URL 和模型，不会保存 API Key；旧版本曾保存的 Key 会在页面加载时自动移除。

简洁模式的 API Key 输入框旁有 📋 粘贴 按钮，可从剪贴板一键填入 Key。

模型列表一键复制

获取模型列表后，每个模型带 📋 复制按钮，过长模型名截断显示但复制完整名。

专业模式（自定义请求）

在 UI 专业模式或 CLI --pro-test 下，可自定义：

• 方法：GET / POST / PUT / DELETE / PATCH
• URL：完整地址，支持占位符 {key} {model}
• Headers：JSON，支持占位符
• Body：JSON 或模板字符串，支持占位符
• 解析规则：点路径提取，如 choices.0.message.content

GitHub Actions 集成

仓库根目录提供可复用的复合 Action，可在 CI 中检查 LLM 端点。它会发起真实请求，可能消耗额度；API Key 应始终来自 GitHub Secret。

- name: Probe LLM endpoint
  uses: xydadada/api-probe@v1
  with:
    base-url: https://api.example.com/v1
    api-key: ${{ secrets.LLM_API_KEY }}
    protocol: openai-chat
    model: example-model
    timeout-ms: '30000'

报错分类

| 状态码 | 含义 | |---|---| | 200-299 且响应结构有效 | ✅ 成功 | | 401 | 认证失败（key 无效） | | 403 | 禁止访问（地域/权限限制） | | 404 | 端点不存在（base url 可能不对） | | 429 | 请求频率超限 | | 5xx | 上游服务器错误 | | 超时/网络错误 | 连接失败 |

结构化错误分析：timeout / unauthorized / invalid_response / network_error / unknown 五类，带中文提示。所有报错提取 error.code/type/message，API Key 自动脱敏（如 sk-****xxxx）。

安全与使用限制

• 测活会真实调用模型，可能产生少量费用；批量测试会产生多次调用。
• 本地服务只监听 127.0.0.1，不应通过端口转发暴露给其他设备。
• 本地 HTTP 入口会校验 Host、Origin 和浏览器跨站请求标记，只接受 127.0.0.1 / localhost 页面访问。
• 专业模式拒绝访问 loopback、局域网、链路本地和云元数据地址，避免被网页或本地程序利用访问内网服务。
• 携带凭据的探测不会自动跟随 HTTP 重定向；如果目标返回 3xx，请改用它给出的最终 API 地址后重新测试。
• 请求体和响应体均有大小限制，超出限制会返回明确错误，而不会无限占用内存。
• 本地服务同时最多执行 8 个可能产生费用的操作，超过限制会返回 429。
• Key 只应临时填入页面或命令行。共享终端记录或截图前，请确认其中没有 Key。

文件结构

api-probe/
├── .github/workflows/ # GitHub Actions 离线回归
├── action.yml         # 可复用的端点测活 GitHub Action
├── api-probe.mjs      # 核心引擎 + CLI + 本地服务
├── package.json       # npm 启动、测试与检查命令
├── providers.json     # 可编辑的 provider 预设库（18 家）
├── public/index.html  # 图形化 UI（双模式 + 增强功能）
├── tests/             # 不访问真实 API 的离线回归测试
├── 启动.bat            # Windows 双击入口（ASCII 兼容层）
├── 启动.ps1            # Unicode 安全的 Windows 启动器
└── README.md          # 本文件

离线验证

npm test       # 运行离线回归测试
npm run check # 语法检查 + 完整离线回归

测试只会启动一个临时的 127.0.0.1 模拟服务，不会读取真实 Key，也不会请求外部 API。

环境要求

• Node.js 18+（系统需能访问你测试的目标 API 所在网络）

参与贡献

欢迎提交 Issue、Discussion 或 Pull Request。详细流程见 CONTRIBUTING.md，社区行为规范见 CODE_OF_CONDUCT.md，版本变化见 CHANGELOG.md。修改核心逻辑、前端或 provider 预设后，请先运行 npm run check；请勿在 Issue、日志、截图或测试文件中提交真实 API Key。

安全问题请按照 SECURITY.md 中的方式报告，不要在公开 Issue 中披露尚未修复的漏洞。

许可证

本项目使用 MIT License。

如果 API Probe 帮你快速定位了接口问题，欢迎点一个 Star，让更多需要排查 LLM API 的人找到它。