本地接口文档
本地 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_navigate | url | 在当前标签页打开网址 |
browser_snapshot | screenshot(可选) | 读取网址、标题、页面文字和带编号的可操作元素 |
browser_evaluate | expression | 在页面里执行 JS 并返回结果,页面有可能察觉 |
browser_click | index | 用真实鼠标点击元素 |
browser_type | index、text、press_enter(可选) | 逐键输入 |
browser_select | index、option | 选择下拉框选项 |
browser_press_key | key | 按键,如 Enter、Tab |
browser_scroll | direction(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.type | none / http / https / socks5 / ssh。ssh 可带 private_key(PEM);动态代理用 mode: "api" + api_url(提取链接)或 mode: "rotate"(账号里带 {session} 的轮换网关),`rotate: "keep" |
proxy_id / proxy_group | 改用代理池里的一条 / 一组(按标签),此时 proxy 以池中记录为准 |
locale_mode | ip:每次打开按代理出口设置时区和语言(默认);manual:用 fingerprint.locale 里的值 |
kernel_mode | latest(默认)或 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、国家、城市、时区 |
7. Cookie
| 方法 | 路径 | 说明 |
|---|---|---|
| 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/upload | multipart file 上传 |
| PUT / DELETE | /api/extensions/{id} | 改名 / 删除 |
| GET | /api/browsers/{id}/backup | 下载窗口备份(.fpbz,窗口需关闭) |
| POST | /api/backup/export | {ids, dir} 批量导出到目录 |
| POST | /api/backup/import | multipart 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 里会说明当前套餐的上限。