PersonaHub 自动化 API

PersonaHub 自动化 API 用于创建和管理 Profile、配置代理与指纹、管理已保存的网站凭据，以及启动和关闭 Profile 浏览器。Profile 在中文界面中称为「身份」。

网页读取、点击、输入、截图等操作需要在启动浏览器后，通过 CDP 或支持 CDP 的自动化工具完成。

1. 接入准备

1. 启动 PersonaHub 桌面客户端并登录账号。
2. 在客户端的自动化设置中启用 API，复制 API Key，确认监听端口。
3. 启动 Profile 前，确认浏览器内核已就绪。
4. 使用期间保持客户端运行、账号已登录，并保持网络可用。

API 只能操作当前登录账号的 Profile，创建数量受账号配额限制。

远程访问时，将 127.0.0.1 替换为运行 PersonaHub 的电脑地址。浏览器、调试端口和返回的文件路径均属于运行客户端的电脑。

2. 通用约定

2.1 鉴权

除 GET /health 外，所有请求需携带：

Authorization: Bearer <API_KEY>

有请求体时使用：

Content-Type: application/json

API Key 不会替代账号登录或扩大账号权限。

2.2 请求和响应

• 请求体为 JSON 对象，不能使用数组、字符串或 null 作为顶层值。
• 请求体上限为 256 KiB；超限时连接可能直接关闭。
• 本文接口成功时均返回 200，包括创建和删除操作。
• 响应为 JSON，并带有 Cache-Control: no-store。
• Profile 和凭据的路径 ID 为 UUID，格式不合法时返回 404。
• 将路径中的 :id、:passwordId、:otpId、:passkeyId 替换为真实 ID。
• 列表接口不提供分页参数。
• PATCH 保留未传字段；嵌套字段的规则见下文。不要用 null 代替省略字段。

错误响应：

{
  "error": "错误说明",
  "code": "not_found"
}

程序应根据 HTTP 状态码和 code 处理错误，不依赖 error 文案或语言。

3. 快速开始

以下命令使用 Bash/zsh 语法。替换 API Key 和已有 Profile 的 UUID 后执行。

export PERSONA_API_BASE='http://127.0.0.1:43110'
export PERSONA_API_KEY='<API_KEY>'

curl -sS "$PERSONA_API_BASE/health"

curl -sS "$PERSONA_API_BASE/v1/engine" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

curl -sS "$PERSONA_API_BASE/v1/profiles" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

export PROFILE_ID='<PROFILE_UUID>'

curl -sS -X POST "$PERSONA_API_BASE/v1/profiles/$PROFILE_ID/launch" \
  -H "Authorization: Bearer $PERSONA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"startupUrl":"https://example.com","extraArgs":["--remote-debugging-port=9222"]}'

启动成功返回：

{"ok": true}

这只表示浏览器已启动，不表示网页、网站登录或 CDP 已就绪。等待调试端口可用后查询：

curl -sS http://127.0.0.1:9222/json/version

使用返回的 webSocketDebuggerUrl，或自动化工具支持的 CDP HTTP 地址连接浏览器。43110 是自动化 API 端口，9222 是示例浏览器调试端口，两者不可混用。多个 Profile 同时启用 CDP 时，应分配不同的调试端口。

关闭本次通过 API 启动的浏览器：

curl -sS -X POST "$PERSONA_API_BASE/v1/profiles/$PROFILE_ID/close" \
  -H "Authorization: Bearer $PERSONA_API_KEY"

4. 服务状态与账号权益

/health 正常不代表账号已登录或浏览器内核已就绪。/v1/engine 的 version 是浏览器内核版本，不是客户端版本；无法取得版本时为空字符串。ready 不代表某个 Profile 已启动或 CDP 可用。

entitlements 字段：

5. Profile 管理

5.1 创建与更新字段

最小创建请求：

{"name": "自动化 Profile"}

创建时未传的配置使用默认值。更新时，proxy 和 fingerprint 只覆盖传入的子字段；代理检测可能影响时区，见第 5.4 节。

局部更新示例：

PATCH /v1/profiles/:id

{
  "name": "自动化 Profile A",
  "startupUrl": "https://example.com",
  "extraArgs": "--remote-debugging-port=9222"
}

这里的 extraArgs 是字符串，和启动接口中的字符串数组不同。保存的参数不支持 shell 引号分组；单个参数含空格时，请通过启动接口的 extraArgs 数组传入。更新 startupUrl 或 extraArgs 时传空字符串可以清空已保存的值。

5.2 代理配置

通过 Profile 的 proxy 字段配置代理。

{
  "name": "美国 Profile",
  "proxy": {
    "protocol": "socks5",
    "host": "proxy.example.com",
    "port": 1080,
    "username": "<PROXY_USERNAME>",
    "password": "<PROXY_PASSWORD>"
  }
}

未配置 Profile 专属代理不等于强制直连；实际网络连接仍可能受到客户端代理链或系统代理设置影响。

5.3 指纹配置

每次创建都会随机选择 CPU 线程数 8/12/16/20/24/32 和内存 16/32 GB；随机组合中，8 线程的性能档位为 3，其余为 4。显式字段覆盖对应预设，更新时省略则保留原值，启动时不会重新随机。

cpuPerformance 档位：0 = Unknown、1 = Low、2 = Mid、3 = High、4 = Ultra。

webrtcIpPolicy 支持：

• disable_non_proxied_udp
• default_public_interface_only
• default_public_and_private_interfaces
• default

允许 UDP 的模式可能暴露直连 IP，而非节点 IP。修改后需关闭并重新启动浏览器。

5.4 代理出口信息

配置了代理且未提供出口信息时，API 会自动检测。检测失败返回 proxy_probe_failed。

如已有检测结果，可以传入 proxyIpInfo：

• 本次请求未明确提供非空的 fingerprint.timezone，且检测结果或 proxyIpInfo 带有时区时，会使用该时区。
• 自动检测不会修改 acceptLanguages；如需调整语言，请显式传入。

5.5 Profile 响应

列表中的每项包含 id、name、startupUrl、extraArgs、createdAt、updatedAt 和可选的 lastLaunchedAt。

详情、创建和更新响应另含：

• proxy：代理连接配置，包含认证密码。
• fingerprint：指纹配置。
• acceptProxyChain：是否接受客户端代理链。
• appearanceLabel、appearanceBackgroundColor、appearanceForegroundColor：外观配置。

6. 浏览器启动与关闭

6.1 启动参数

launch 和 command 接受相同请求体；不需要临时参数时发送 {}。

{
  "startupUrl": "https://example.com",
  "extraArgs": ["--remote-debugging-port=9222"]
}

启动参数依次包含 Profile 已保存参数、客户端全局启动参数及本次 extraArgs。清空 Profile 已保存参数不会清除客户端全局参数。

这些参数仅用于本次调用，不修改 Profile 已保存的值。extraArgs 不能覆盖 PersonaHub 管理的数据目录和浏览器生命周期参数。

launch 成功只代表浏览器已启动。重复调用可能关闭并重新启动该 Profile，请勿用它轮询运行状态。

6.2 获取启动命令

command 响应字段：

将返回值原样交给进程启动 API，在运行 PersonaHub 的电脑上启动浏览器，不要拼接成 shell 命令或覆盖数据目录。

如使用 --remote-debugging-pipe，应选择 command，由调用方创建进程并连接调试管道；launch 不返回调试管道。

6.3 使用限制

• 使用浏览器期间保持 PersonaHub 桌面客户端运行。
• close 不管理通过客户端界面启动的浏览器，也不管理调用方根据 command 自行启动的进程。
• 没有可关闭的 API 启动记录时，返回 404，错误码为 not_running。浏览器已自行退出时，首次 close 仍可能成功，因此不能用此接口判断运行状态。
• close 成功表示已请求关闭，不保证浏览器已退出。
• 不要对同一 Profile 并发启动多个实例。

7. 已保存的网站凭据

7.1 网站密码

保存请求：

{
  "origin": "https://example.com",
  "username": "user@example.com",
  "password": "<WEBSITE_PASSWORD>"
}

PATCH 至少提供上述字段之一，未传字段保留原值，不允许空字符串。signon_realm 自动生成，不接受作为请求字段。

摘要包含 id、origin、signon_realm、username；单条详情另含 password。保存相同网站登录域和用户名时会更新已有条目。保存接口不返回 ID，需要再次查询列表。

修改会在后续启动时提供给浏览器。删除不会修改网站账号，也不会移除运行中浏览器已加载的凭据；后续浏览器同步可能覆盖修改或重新创建已删除条目。

7.2 TOTP 动态验证码

保存请求字段：

列表和保存响应包含 id、label、issuer、accountName、algorithm、digits、period，不返回密钥。

同一 Profile 下相同的标准化密钥会更新或恢复已有条目；不同密钥创建新条目。再次保存时，省略的元数据和设置采用默认值，不保留旧值。

验证码响应示例：

{
  "id": "<OTP_UUID>",
  "code": "012345",
  "expiresAt": "2026-09-17T08:00:30.000Z"
}

code 为字符串，应保留前导零。验证码按运行 PersonaHub 的电脑时钟生成；expiresAt 为 UTC ISO 时间。接口不会自动提交验证码；保存或删除条目也不会开启或关闭网站上的两步验证。

7.3 Passkey

每项包含 id、rpId、userName、userDisplayName，不返回私钥。自动化 API 不提供创建或导入 Passkey 的接口。

删除影响后续启动，不会在网站注销凭据，也不会移除运行中浏览器已加载的副本。在浏览器中使用 Passkey 的套餐要求见 Passkey 使用指南。

8. 常见错误

相关文档

• 创建 Profile
• 启动 Profile 浏览器
• 启用 CDP
• 网站密码管理
• TOTP 使用指南
• Passkey 使用指南