本地接口文档

本地 HTTP 接口:新建、打开、关闭窗口,指纹、代理池、Cookie、群控、RPA,Puppeteer / Playwright / Selenium 接入示例,比特风格兼容接口

棱镜 PrintVeil 客户端在本机提供一套 HTTP 接口,用来从脚本里新建、打开、关闭窗口,并把 Puppeteer / Playwright / Selenium 连到打开的窗口上。另有一组与比特浏览器参数兼容的接口,已有的自动化脚本改个地址就能用。

1. 基本约定

项说明
地址http://127.0.0.1:55301,只接受本机访问。端口可在客户端「设置」里修改,或启动时用 -port 指定
令牌每个请求带请求头 X-FPB-Token: <令牌>(或 Authorization: Bearer <令牌>)。令牌在客户端「API 文档」页可以复制,也在数据目录(默认 %APPDATA%\fpb)的 api-token 文件里,每台电脑不同
请求体JSON,Content-Type: application/json
返回成功 {"ok":true,"data":…};失败 {"ok":false,"error":"错误说明","code":"错误码"}
前提客户端已登录账号。未登录时除 /api/health 外的接口都返回 401

HTTP 状态码:

状态含义
400参数错误,error 里有具体说明
401没带令牌(code 为 token_required)或客户端未登录(带 auth_required: true)
403超出套餐额度(窗口总数、每天打开次数、手机指纹权益)或团队成员没有相应权限
404窗口 / 分组 / 代理不存在
429自动化调用太频繁:按套餐的每分钟次数计(免费版 60 次 / 分钟,付费套餐不限)

安全说明:接口不发任何 CORS 头,网页里的脚本无法调用;Host 不是本机地址或请求带跨站标记的一律拒绝。请不要用端口转发把接口暴露到局域网或公网,远程调用请走 SSH 隧道。

2. 快速开始

API=http://127.0.0.1:55301
TOKEN=你的令牌

# 1. 新建窗口:不带指纹时自动生成一套(按 generate 里的地区 / 平台 / 机型)
curl -X POST $API/api/browsers -H "X-FPB-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"name":"Amazon-US-01","generate":{"region":"US"},"proxy":{"type":"socks5","host":"1.2.3.4","port":1080,"username":"u","password":"p"}}'

# 2. 打开窗口:返回 DevTools 地址
curl -X POST $API/api/browsers/<id>/open -H "X-FPB-Token: $TOKEN"
# {"ok":true,"data":{"id":"…","seq":12,"pid":4321,"cdp_port":51429,"ws":"ws://127.0.0.1:51429/devtools/browser/…","http":"http://127.0.0.1:51429","already_running":false}}

# 3. 用完关闭(关闭时会保存 Cookie)
curl -X POST $API/api/browsers/<id>/close -H "X-FPB-Token: $TOKEN"

Node.js + Puppeteer

const puppeteer = require('puppeteer-core');   // npm i puppeteer-core
const API = 'http://127.0.0.1:55301', TOKEN = '你的令牌', id = '窗口ID';

const res = await fetch(`${API}/api/browsers/${id}/open`, { method: 'POST', headers: { 'X-FPB-Token': TOKEN } }).then(r => r.json());
if (!res.ok) throw new Error(res.error);

const browser = await puppeteer.connect({ browserWSEndpoint: res.data.ws, defaultViewport: null });
const page = await browser.newPage();
await page.goto('https://www.browserscan.net');
console.log(await page.title());

browser.disconnect();   // 只断开连接,窗口保持打开;要关窗口调 /close
await fetch(`${API}/api/browsers/${id}/close`, { method: 'POST', headers: { 'X-FPB-Token': TOKEN } });

Node.js + Playwright

const { chromium } = require('playwright');
const res = await fetch(`${API}/api/browsers/${id}/open`, { method: 'POST', headers: { 'X-FPB-Token': TOKEN } }).then(r => r.json());
const browser = await chromium.connectOverCDP(res.data.http);   // 用 http 地址
const context = browser.contexts()[0];
const page = await context.newPage();
await page.goto('https://example.com');

Python + Selenium

import requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

API, TOKEN, ID = 'http://127.0.0.1:55301', '你的令牌', '窗口ID'
r = requests.post(f'{API}/api/browsers/{ID}/open', headers={'X-FPB-Token': TOKEN}).json()
assert r['ok'], r['error']

opts = Options()
opts.add_experimental_option('debuggerAddress', r['data']['http'].replace('http://', ''))
driver = webdriver.Chrome(options=opts)     # chromedriver 版本需与内核主版本一致(见 GET /api/kernels)
driver.get('https://example.com')
print(driver.title)
driver.quit()
requests.post(f'{API}/api/browsers/{ID}/close', headers={'X-FPB-Token': TOKEN})

不用 WebSocket 操作页面

POST /api/mcp 是普通的 HTTP 接口,能发 HTTP 请求的语言都可以用它读写 DOM,不需要 CDP 或 WebSocket 库。易语言、PHP 这类写 WebSocket 比较麻烦的语言建议用这种方式。

curl -X POST $API/api/mcp -H "X-FPB-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"browser_evaluate","arguments":{"profile":"<id>","expression":"document.title"}}}'
# {"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"Example Domain","type":"text"}]}}

结果在 result.content[0].text;操作失败时 result.isError 为 true,text 是错误说明。窗口要先打开,profile 填窗口 ID。

工具参数作用
browser_navigateurl在当前标签页打开网址
browser_snapshotscreenshot(可选)读取网址、标题、页面文字和带编号的可操作元素
browser_evaluateexpression在页面里执行 JS 并返回结果,页面有可能察觉
browser_clickindex用真实鼠标点击元素
browser_typeindex、text、press_enter(可选)逐键输入
browser_selectindex、option选择下拉框选项
browser_press_keykey按键,如 Enter、Tab
browser_scrolldirection(down / up)滚动页面
browser_back后退

index 是最近一次 browser_snapshot 返回的元素编号,页面变化后要重新取。

其它语言

源码仓库的 examples/api-demo 目录有易语言、Python、Node.js、Java、C#、Go、PHP、curl 的完整示例,还有一份 Postman 集合,说明见该目录的 README。

易语言用系统自带的 WinHttp 组件就能调用,不依赖精易模块。把下面的代码粘贴到程序集里:

.版本 2

.子程序 发送请求, 文本型
.参数 方法, 文本型
.参数 路径, 文本型
.参数 请求体, 文本型
.局部变量 http, 对象

http.创建 (“WinHttp.WinHttpRequest.5.1”, )
http.方法 (“SetTimeouts”, 5000, 5000, 180000, 180000)
http.方法 (“Open”, 方法, “http://127.0.0.1:55301” + 路径, 假)
http.方法 (“SetRequestHeader”, “X-FPB-Token”, “你的令牌”)
http.方法 (“SetRequestHeader”, “Content-Type”, “application/json; charset=utf-8”)
http.方法 (“Send”, 请求体)
返回 (http.读文本属性 (“ResponseText”, ))

3. 窗口

方法路径说明
GET/api/browsers?group=&q=窗口列表,可按分组(含子分组)和关键字筛选;每项带运行状态 running、pid、cdp_port、ws
POST/api/browsers新建窗口,请求体为窗口对象(见下);不带 fingerprint 时自动生成,可用 generate 指定地区、平台、机型
GET/api/browsers/{id}窗口详情
PUT/api/browsers/{id}更新窗口(整个对象提交;未改的字段原样传回)
DELETE/api/browsers/{id}移入回收站;加 ?permanent=1 连数据一起删除
POST/api/browsers/{id}/open打开窗口,返回 {id, seq, pid, cdp_port, ws, http, already_running, warning}
POST/api/browsers/{id}/close关闭窗口
POST/api/browsers/{id}/activate把窗口带到前台
POST/api/browsers/{id}/open-url{url} 在运行中的窗口里新开一个标签页
POST/api/browsers/{id}/proxy-check检测该窗口代理的出口 IP,并按出口更新时区语言(跟随 IP 模式)
POST/api/browsers/{id}/renew-ip动态代理换一个 IP
POST/api/browsers/quick一次性窗口:{platform, region, proxy, proxy_id, url} 生成指纹并马上打开,返回同打开窗口;关闭后连数据一起删除,不同步
POST/api/browsers/{id}/home{"action":"reset"} 检测一次出口并设为常驻地;{"action":"clear"} 清除,下次打开时重新记录。打开窗口时出口不在常驻地会自动换 IP / 提醒 / 拒绝(设置 home_guard),warning 里有说明
POST/api/browsers/{id}/checkup在窗口里运行指纹体检,结果见 GET /api/checkup/{id}
GET/api/browsers/opened正在运行的窗口及其进程、端口
POST/api/browsers/batch批量操作,见下

批量操作 POST /api/browsers/batch:

请求体作用
{"action":"open","ids":[…]} / "close" / "delete"批量打开 / 关闭 / 移入回收站
{"action":"group","ids":[…],"group_id":"…"}移动到分组
{"action":"extensions","ids":[…],"add":["扩展ID"],"remove":[…]}增减扩展
{"action":"upgrade_kernel","ids":[…],"kernel_major":0}换到最新(或指定)内核,指纹保留;运行中的窗口跳过
{"action":"kernel_mode","ids":[…],"kernel_mode":"latest"}latest 打开时跟随最新内核 / fixed 固定当前内核
{"action":"edit","ids":[…],"edit":{…}}批量修改,只写要改的字段:name(模板:{name} 原名、{seq} 序号、{n} 选中顺序)、remark + remark_mode(set / append)、tags_set / tags_add / tags_remove、open_urls、locale_mode(ip / manual)、traffic_saver、restore_session
{"action":"regen_fp","ids":[…]}同类设备重新生成指纹(新种子),运行中的窗口跳过

返回 {"窗口ID":"ok" 或 错误说明}。

窗口对象

{
  "name": "Amazon-US-01",
  "group_id": "",
  "remark": "",
  "tags": ["电商", "美区"],
  "proxy": { "type": "socks5", "host": "1.2.3.4", "port": 1080, "username": "u", "password": "p" },
  "proxy_id": "",
  "locale_mode": "ip",
  "kernel_mode": "latest",
  "open_urls": ["https://www.amazon.com"],
  "extensions": [],
  "restore_session": false,
  "traffic_saver": false,
  "fingerprint": { "...": "自动生成或 POST /api/fingerprint/generate 的结果" }
}
字段说明
name必填
group_id分组 ID,空为未分组
proxy.typenone / http / https / socks5 / ssh。ssh 可带 private_key(PEM);动态代理用 mode: "api" + api_url(提取链接)或 mode: "rotate"(账号里带 {session} 的轮换网关),`rotate: "keep"
proxy_id / proxy_group改用代理池里的一条 / 一组(按标签),此时 proxy 以池中记录为准
locale_modeip:每次打开按代理出口设置时区和语言(默认);manual:用 fingerprint.locale 里的值
kernel_modelatest(默认)或 fixed
open_urls启动时打开的网址,每项一个标签页
extensions扩展 ID 列表(GET /api/extensions)
restore_session打开时恢复上次的标签页
traffic_saver省流量:不加载图片,视频点击才播放
fingerprint指纹档案。只读字段 fingerprint.platform(windows / macos / android / ios)、fingerprint.model、fingerprint.gpu_label、fingerprint.screen 等可用来展示

列表和详情返回时还带 seq(窗口序号,兼容接口可用它代替 id)、created_at、last_open_at、open_count、ip_info(最近一次出口检测)、checkup(最近一次体检分数)。

4. 指纹

方法路径说明
POST/api/fingerprint/generate生成一份指纹(不入库):{platform, model, region, form_factor, brand, gpu, kernel_major},都可省略。platform 为 windows(默认)/ macos / android / ios,手机平台需要专业版及以上;region 为国家代码,决定语言和常见机型;form_factor 为 desktop / laptop;brand 为 Chrome / Edge
GET/api/platforms?kernel=可用平台和各平台的机型列表(model 的取值)
GET/api/regions地区列表
GET/api/gpus?kernel=可指定的显卡系列(gpu 的取值)
GET/api/kernels本机已安装的内核:{version, major, supported, deprecated}

生成的对象可直接作为新建窗口的 fingerprint,也可以放进 generate 让新建时按同样的条件生成。

5. 分组

方法路径说明
GET/api/groups分组列表,parent_id 为空是顶级,count 为直接包含的窗口数
POST/api/groups{name, parent_id, sort}
PUT/api/groups/{id}改名、移动
DELETE/api/groups/{id}删除分组,其中的窗口变为未分组,子分组上移一级

6. 代理池

方法路径说明
GET/api/proxies代理池列表,每条带最近一次检测结果 status / last
POST/api/proxies单条 {name, type, host, port, username, password, tags};或批量 {"lines":"每行一个地址","def_type":"socks5"},支持 scheme://user:****@host:port、host:port:user:pass、host:port 等写法,行尾 # 名称 可命名
PUT/api/proxies/{id}修改
DELETE/api/proxies/{id}删除;加 ?force=1 同时解绑使用它的窗口
POST/api/proxies/check{ids} 检测,空为全部启用的
POST/api/proxies/{id}/check检测一条
POST/api/proxies/assign`{browser_ids, proxy_ids, mode:"auto"
POST/api/proxy/check不入库地检测任意代理 {type, host, port, username, password},返回出口 IP、国家、城市、时区
方法路径说明
GET/api/browsers/{id}/cookies?format=json导出 Cookie,format 为 json(默认)或 netscape;窗口未打开时在后台临时读取
POST/api/browsers/{id}/cookies导入:{"cookies":[…]} 或 {"data":"JSON 或 Netscape 文本"},"replace":true 先清空再导入
DELETE/api/browsers/{id}/cookies清空

Cookie 对象与浏览器扩展常见的导出格式一致:{name, value, domain, path, expirationDate, hostOnly, httpOnly, secure, session, sameSite}。

8. 扩展、备份、窗口排列

方法路径说明
GET/api/extensions扩展库
POST/api/extensions/import{path} 导入本机的 crx / zip / 目录
POST/api/extensions/uploadmultipart file 上传
PUT / DELETE/api/extensions/{id}改名 / 删除
GET/api/browsers/{id}/backup下载窗口备份(.fpbz,窗口需关闭)
POST/api/backup/export{ids, dir} 批量导出到目录
POST/api/backup/importmultipart file(可多个)或 {path, name, group_id, no_data}
GET/api/displays显示器列表
POST/api/windows/arrange`{ids, monitor, mode:"grid"
GET/api/windows/bounds运行中窗口的位置和大小

9. 群控(窗口同步)

方法路径说明
GET/api/sync同步状态 {running, master, options, peers}
POST/api/sync/start{master, slaves:[…], options:{mouse, keyboard, tabs, nav, right_click, delay_min, delay_max}},窗口需已打开
POST/api/sync/stop停止
PUT/api/sync/options修改同步内容,立即生效
POST/api/sync/action`{type:"url"

10. RPA

方法路径说明
GET / POST / PUT / DELETE/api/rpa/scripts[/{id}]脚本 `{name, type:"flow"
POST/api/rpa/scripts/{id}/test{browser_id, vars} 在一个窗口上试运行,返回运行 ID
GET / POST / PUT / DELETE/api/rpa/tasks[/{id}]任务 {name, script_id, browser_ids, group_id, schedule:{type, every_min, at, cron}, concurrency, open_before, close_after, timeout_sec, vars, enabled}
POST/api/rpa/tasks/{id}/run立即运行,可带 browser_ids 只跑部分窗口
GET/api/rpa/runs?task=&limit=运行记录;GET /api/rpa/runs/{id} 完整日志;POST /api/rpa/runs/{id}/cancel 停止

11. 其他

方法路径说明
GET/api/health{version, kernels, running, logged_in},不需要令牌
GET/api/browsers/{id}/traffic该窗口经代理的累计流量;DELETE 清零
GET/api/browsers/{id}/accounts/{aid}/code窗口里保存的平台账号当前的两步验证码 {code, remaining, period}
POST/api/totp{secret} 按密钥计算当前验证码
GET/api/risk每个窗口的风险等级、分数、问题、出口历史和常驻地 home
GET/api/risk/links关联图谱:clusters 是互相关联的窗口组,links 每条是两个窗口之间的一条线索(kind:account 同一个账号、seed 指纹相同、ip 同一出口、ip_history 30 天内用过同一 IP、subnet 同一网段)
POST/api/risk/scan{ids?, wait?} 检测出口并重新评估;wait:true 等扫描完再返回新告警
GET/api/risk/fixes一键修复方案:每项 {browser_id, code, action, title, detail, warn, error},action 为 regen_fp 重新生成指纹 / assign_proxy 分配空闲代理 / renew_ip 换 IP / home_ip 换 IP 回常驻地 / locale_ip 时区语言跟随 IP;有 error 的项现在不能执行
POST/api/risk/fixes{items:[{browser_id, action}]} 执行修复,返回每项的 ok 和说明;改过的窗口会在后台重新检测出口
POST/api/netdiag网络诊断:本机直连、DNS、系统代理、VPN 网卡、本机代理端口、前置代理、代理服务器连通性、系统时间;每项 {status, detail, hint, fix},fix 是可以直接 PUT /api/settings 的建议设置
GET/api/browsers/{id}/timeline窗口时间线:打开(出口、警告)、没打开的原因、关闭(时长)、改设置、换 IP、常驻地、修复、风险告警,最新的在前;?limit= 限制条数
POST/api/shutdown关闭所有窗口、保存 Cookie 后退出客户端

12. 兼容接口(比特浏览器风格)

为了复用已有脚本,以下接口的路径、参数和返回格式与比特浏览器一致:POST JSON,用 id 或 seq 指定窗口,返回 {"success":true,"data":…},失败 {"success":false,"msg":"…"}。同样需要 X-FPB-Token 请求头。

路径参数返回
/browser/open{id} 或 {seq}{ws, http, pid, seq},http 不带 http:// 前缀,可直接给 Selenium 的 debuggerAddress
/browser/close{id} 或 {seq}
/browser/close/all
/browser/list{groupId, name}{list, totalNum}
/browser/detail{id}窗口详情
/browser/delete{id}移入回收站
/browser/opened/ids运行中的窗口 ID
/browser/pids{窗口ID: 进程号}
/browser/ports{窗口ID: 调试端口}
/browser/cookies/get{id}Cookie 列表
/browser/cookies/set{id, cookies:[…]} 或 {id, cookiesStr, replace}
/browser/cookies/clear{id}
/health"ok"

迁移现有脚本:把地址从比特的 127.0.0.1:54345 换成 127.0.0.1:55301,请求头加上 X-FPB-Token,窗口 ID 换成本软件的(可用客户端的「从比特导入」一键导入窗口,导入后 /browser/list 返回的就是新 ID)。

13. 额度与限制

项免费版付费套餐
接口调用频率每分钟 60 次不限
每天打开窗口次数30 次不限
窗口总数10 个按套餐
手机指纹(Android / iOS)—专业版及以上

超出额度返回 403,频率超限返回 429,error 里会说明当前套餐的上限。

来源:仓库 docs/开发者接口.md