API 概述

新版 API 文档

完整接口文档已迁移至 doc.virtualbrowser.cc，包含分组目录、请求示例与字段说明。本页保留客户端本地 API 的启用与鉴权说明。

VirtualBrowser 由运行中的桌面客户端提供 HTTP API。它不是官网登录接口，也不是 IPGeo 查询服务。客户端行为按本地源码核对（2026-11-04）；ApiFox 可作为补充参考；全部接口见 API 索引。

1. 启用服务

1. 打开客户端，登录有效的专业版会员账号。
2. 进入 API 页面，复制服务地址和 api-key。
3. 保持客户端运行。无人值守启动见 CLI 模式。

基础地址为 http://127.0.0.1:{port}，或客户端实际显示的地址。服务端口动态分配，9000 只是示例。启动环境返回的是另一个用于 CDP 自动化的调试端口，两者不能混用。

2. 请求鉴权

请求头使用客户端本地 API key，不是官网登录 token，也不是 IPGeo key：

api-key: YOUR_API_KEY
Content-Type: application/json

GET 业务参数放在 URL Query 中；POST 业务参数放在 JSON 请求体中。不要把密钥拼到 URL 中。

当前客户端统一认证

部分 ApiFox 页面把 api-key 标为可选或未标必填，当前客户端对这些路由统一鉴权，因此所有示例均携带此请求头。公开示例中的密钥不是可用凭据，必须从你自己的客户端复制。

3. 第一次调用

各接口页的 cURL 示例使用 Bash 换行语法。Windows 可使用 curl.exe 单行命令，或直接使用 PowerShell：

$base = 'http://127.0.0.1:9000' # 替换为 API 页面显示的地址
$headers = @{ 'api-key' = 'YOUR_API_KEY' }
Invoke-RestMethod -Uri "$base/api/getBrowserList" -Headers $headers

$body = @{ id = 1 } | ConvertTo-Json
$launch = Invoke-RestMethod -Method Post -Uri "$base/api/launchBrowser" -Headers $headers -ContentType 'application/json' -Body $body -TimeoutSec 60
if (-not $launch.success) { throw $launch.error }
$launch.data.debuggingPort

使用 Playwright / Puppeteer 时连接 http://127.0.0.1:{debuggingPort}，不是本地 API 端口，见 Playwright 接入。

4. 响应解析

大部分成功响应使用：

{ "success": true, "data": {} }

data 不一定存在，也不一定是对象，可能是数组、布尔值或单个环境对象。有些接口只返回 success，或包含 message 等其他顶层字段。

• 启动环境：端口位于 data.debuggingPort。
• 内核版本：data 为数组，total、majors 位于顶层。
• 读取 Cookie：data 直接为 Cookie 数组，不是 cookie.jsonStr。
• 运行状态：ApiFox 定义为原始布尔值，当前客户端返回 success/data 包装；接口页提供兼容读取方式。

失败通常返回：

{ "success": false, "error": "错误信息" }

同时检查 HTTP 状态和响应体，不要仅因 HTTP 200 就认为成功，也不要强制要求所有成功响应都有 data。详见 错误码与排查。

5. 调用建议

• 从列表接口取得 ID，不要假定环境 ID 连续递增。
• 指定内核前先查 本地可用版本，示例版本不是默认版本。
• 读写 Cookie、删除环境数据前先关闭环境；破坏性操作前先备份。
• 批量调用限制并发；启动超时后先查 运行列表，不要直接重复启动。
• 不在公开日志记录密钥或平台密码；仅允许可信来源访问本地 API 服务。
• 窗口排列 当前仅支持 Windows，空请求体排列所有已启动环境。

相关文档

• 全部接口 · 环境参数说明
• 自动化示例 · MCP

安全边界与访问日志

当前客户端 HTTP 服务绑定 0.0.0.0；localhost 只是推荐的本机访问地址，不能保证局域网或其他网络无法连接。服务使用 HTTP，请使用防火墙限制可信来源；跨主机访问时应使用受信任的加密通道，不要把端口直接暴露到公网。API key 不等于 IPGeo key，可在客户端更新；密钥更新后旧值失效。

账号接口可能返回明文密码，Cookie、代理认证、浏览器完整参数和 MCP 页面内容也可能敏感。不要发布真实请求、响应或截图。请求返回 X-Request-Id，可用于关联客户端的 api-access.log；Windows 默认位置为 %APPDATA%/VirtualBrowser/User Data/api-access.log，超过约 20 MiB 会轮转至 .1。日志脱敏不保证覆盖所有字段，分享前必须人工删除邮箱、账号、password_value、Cookie、密钥和代理凭据。

POST JSON 请求体当前大小上限为 10 MiB；超限可能返回 HTTP 413，且响应未必是本接口的 JSON 错误格式。