本地 API 文档：用脚本管理浏览器环境。

概览

本地 API 是 Prism Pro 功能，适合用自己的脚本批量管理环境：按业务数据创建环境，按顺序启动、检查状态，用完后关闭。它只管理环境本身，不读取 Cookie、密码、代理凭据和网页内容，也不提供 Puppeteer / Playwright 调试端点。需要让 AI 读取网页、点击和填写表单时，请使用 MCP。

快速开始

1. 启动本地 API

   在 Prism 左侧打开“自动化 API”，点击“启动本地 API”。这个功能需要 Prism Pro。

2. 复制地址和令牌

   窗口会显示“API 地址”和“本次访问令牌”。令牌只在启动成功时显示一次，请立即复制；之后需要新令牌时，停止并重新启动 API。

3. 发送第一个请求

   在终端中设置两个变量，检查服务状态并列出环境。返回 "state": "running" 说明地址和令牌可用。

PRISM_API='http://127.0.0.1:43123'   # the API address shown in Prism
PRISM_TOKEN='<token>'                # the token shown in Prism

curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/status"
curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles"

Windows PowerShell 中的 curl 是另一个命令的别名，请输入 curl.exe，或使用 PowerShell 自带的 Invoke-RestMethod：

$api = 'http://127.0.0.1:43123'
$headers = @{ Authorization = 'Bearer <token>' }
(Invoke-RestMethod -Uri "$api/v1/profiles" -Headers $headers).result | Format-Table serialNumber, name, status

请求规则

API 只接受这台电脑上由脚本或程序发出的请求。不满足下列规则的请求不会执行，并返回下表中的错误：

Prism 按收到的顺序逐个处理本地 API 和 MCP 请求。启动环境要检测代理、打开浏览器，通常需要几秒，这期间后续请求会排队。请等上一个请求返回后再发下一个。

接口一览

{id} 是环境 ID，可以从 GET /v1/profiles 的结果中取得。成功响应的 HTTP 状态都是 200；除 GET /v1/status 外，结果放在 result 字段中。API 不提供修改和删除环境的接口。

环境对象

环境列表、环境状态、启动和关闭都返回同样的环境对象：

{
  "result": {
    "id": "8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70",
    "serialNumber": 12,
    "name": "Shop A",
    "group": "Project A",
    "tags": ["automation"],
    "status": "running",
    "lastOpenedAt": "2026-10-02T08:30:00.000Z"
  }
}

接口不返回代理地址和凭据、指纹参数、Cookie、密码、网站数据或扩展数据。

查询、启动与关闭

GET /v1/status

返回服务状态，用来确认地址和令牌可用。这是唯一不放在 result 中的响应：

{
  "state": "running",
  "transport": "loopback",
  "protocolVersion": 1
}

GET /v1/profiles

返回环境对象数组，最近修改的环境排在前面。回收站中的环境不会出现。

GET /v1/profiles/{id}/status

返回一个环境的当前状态。环境不存在或已移入回收站时返回 404 PROFILE_NOT_FOUND。

POST /v1/profiles/{id}/start

• 与在界面中点击“打开”相同：检查内核和 Pro 内核授权，检测代理与出口变化，然后打开浏览器窗口。成功后返回状态为 running 的环境对象。
• 环境已经在运行时，直接返回当前状态，不会重复打开。
• 一个启动请求返回后，Prism 才处理下一个请求。批量启动时逐个调用即可；同时运行多少个环境取决于电脑的内存和 CPU。
• 没有对应内核、代理检测未通过、代理出口 IP 有变化（策略为 block）或有遗留进程时，启动失败并返回 502，error.message 说明原因。
• 界面中需要你确认才能继续的情况，通过 API 会直接失败，例如代理出口的地理位置数据互相矛盾。遇到这类错误，可以在 Prism 界面中打开该环境，或把网络身份改为 manual。
• 调用过启动接口的环境（包括调用时已经在运行的）会被记录下来，在“自动化 API”窗口点击“紧急停止”时一并关闭。“停止 API”以及 MCP 窗口中的停止和紧急停止只会停止 API，这些环境保持打开。

POST /v1/profiles/{id}/close

关闭浏览器窗口，保留环境数据，返回状态为 closed 的环境对象；环境没有运行时也直接返回 closed。如果浏览器 8 秒内没有退出、仍占用数据目录，返回状态为 orphaned，再调用一次关闭会结束遗留进程。

PROFILE_ID='8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70'   # an id from GET /v1/profiles
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/start"
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/close"

创建环境

创建接口把环境保存为关闭状态，不会打开浏览器。所有字段都可以省略：省略的字段使用与界面“新建环境”相同的默认值，每个环境都会生成新的指纹种子。未知字段会被拒绝。

创建一个环境

curl -X POST "$PRISM_API/v1/profiles" \
  -H "Authorization: Bearer $PRISM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-b-001" \
  -d '{
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "startUrls": ["https://example.com/"],
    "proxy": { "protocol": "socks5", "host": "203.0.113.10", "port": 1080, "username": "user", "password": "pass" }
  }'

成功后返回新环境：

{
  "result": {
    "id": "3b1f7a52-9c4e-4d2b-8f60-1a2b3c4d5e6f",
    "serialNumber": 13,
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "status": "closed"
  }
}

批量创建

POST /v1/profiles/batch 的请求体是 profiles 数组，一次 1–50 个；每个元素的写法与单个创建相同，只是 requestKey 要写在顶层或请求头中。Prism 先校验全部配置，任何一个有误都不会创建，错误信息会指出是哪个环境的哪个字段（profiles[1] 表示第二个，从 0 开始计数）。结果按输入顺序返回：

{
  "requestKey": "shops-batch-001",
  "profiles": [
    { "name": "Shop C", "group": "Project A" },
    { "name": "Shop D", "group": "Project A", "fingerprint": { "platform": "windows" } }
  ]
}

{
  "result": {
    "profiles": [
      { "id": "…", "serialNumber": 14, "name": "Shop C", "group": "Project A", "tags": [], "status": "closed" },
      { "id": "…", "serialNumber": 15, "name": "Shop D", "group": "Project A", "tags": [], "status": "closed" }
    ],
    "count": 2
  }
}

环境字段

代理字段

指纹字段

硬件模板

模板与 platform 不一致时请求会被拒绝。窗口位置与大小、Cookie、扩展数据等无法通过 API 设置，创建后可以在 Prism 界面中修改。

重试与去重

网络中断或请求超时时，你可能不知道环境是否已经创建。为每次创建提供一个请求标识，重试就不会重复创建：

• 在请求头 Idempotency-Key 或请求体 requestKey 中提供 8–128 个字符的标识，可用英文字母、数字和 . _ : -。两处都填时必须相同。
• 24 小时内用相同的标识和相同的内容重试，返回第一次创建的环境（HTTP 200），Prism 重启后依然有效。
• 标识相同但内容不同时返回 409 IDEMPOTENCY_CONFLICT。第一次创建的环境已被删除（包括移入回收站）时返回 409 IDEMPOTENCY_RESULT_GONE，不会悄悄重建；需要重新创建时请换一个标识。
• 超过 24 小时后，同一个标识视为新请求。
• 24 小时内最多保留 1000 个带标识的请求，这个上限与 MCP 创建共用（MCP 每次创建都会占用一个），达到上限时返回 429 IDEMPOTENCY_CAPACITY，旧记录过期后恢复。
• 标识和请求内容只以加密摘要保存在这台电脑上，不保存代理密码原文。

建议用业务数据生成标识，例如表格行号或订单号：shop-b-001。

错误处理

请求在入口被拒绝时（见“请求规则”），error 是一个字符串，例如 {"error":"unauthorized"}。Prism 处理请求时出错，error 是一个对象：

{
  "error": {
    "code": "INVALID_PROFILE_INPUT",
    "message": "Invalid profile creation request; see details",
    "retryable": false,
    "details": [
      { "path": "profiles[1].proxy.port", "message": "Too big: expected number to be <=65535" }
    ]
  }
}

程序请根据 HTTP 状态和 code 判断；message 是给人看的说明，部分为中文，措辞可能随版本调整。retryable 为 true 时可以稍后原样重试。details 只出现在创建参数错误中，最多 20 项，不会回显提交的值。

MCP_REQUEST_FAILED 是 Prism 内部沿用的通用错误名，本地 API 也使用它。

代码示例

把示例中的地址和令牌换成 Prism 窗口中显示的值。示例会创建环境，并启动、关闭新建的环境。

Python

需要 requests（pip install requests）：

import requests

API = "http://127.0.0.1:43123"   # the API address shown in Prism
TOKEN = "<token>"                # the token shown in Prism

session = requests.Session()
session.headers["Authorization"] = f"Bearer {TOKEN}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=70, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code}: {body['error']}")
    return body.get("result", body)

created = call("POST", "/v1/profiles/batch",
               headers={"Idempotency-Key": "shops-batch-002"},
               json={"profiles": [{"name": "Shop C"}, {"name": "Shop D"}]})
for profile in created["profiles"]:
    print("created", profile["serialNumber"], profile["id"])

profiles = call("GET", "/v1/profiles")
for profile in profiles:
    print(profile["serialNumber"], profile["name"], profile["status"])

first = created["profiles"][0]["id"]
print(call("POST", f"/v1/profiles/{first}/start")["status"])   # running
print(call("POST", f"/v1/profiles/{first}/close")["status"])   # closed

Node.js

Node.js 18 起自带 fetch，无需安装依赖：

// prism.mjs — run with: node prism.mjs (Node.js 18 or later)
const API = 'http://127.0.0.1:43123' // the API address shown in Prism
const TOKEN = '<token>'              // the token shown in Prism

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(70_000),
  })
  const data = await response.json()
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data.error)}`)
  return data.result ?? data
}

const profile = await call('POST', '/v1/profiles', {
  name: 'Shop E',
  fingerprint: { language: 'en-US', timezone: 'America/New_York', networkIdentityMode: 'manual' },
}, { 'Idempotency-Key': 'shop-e-001' })
console.log('created', profile.serialNumber, profile.id)

console.log((await call('POST', `/v1/profiles/${profile.id}/start`)).status) // running
console.log((await call('POST', `/v1/profiles/${profile.id}/close`)).status) // closed

与 MCP 的关系

本地 API 面向你自己写的脚本；AI 客户端请通过 MCP 连接 Prism。MCP 使用独立的令牌和权限，只有在“本地 AI · MCP”中允许的环境对 AI 可见，AI 不能调用本地 API。两者共用同一个本地服务和每 60 秒 120 个请求的额度；停止 MCP 或紧急停止 MCP 时，本地 API 也会停止。

AI 也可以用 MCP 工具 prism_create_profile 和 prism_create_profiles 创建环境，参数与本页相同。这需要你在“本地 AI · MCP”中打开“允许 AI 创建环境”（默认关闭）；新环境能否被 AI 控制，取决于你设置的环境授权方式。MCP 与本地 API 的请求标识分开计算，但共用 24 小时内 1000 个的记录上限。

安全建议

• 令牌相当于这台电脑上管理环境的钥匙：不要写进代码仓库、日志或聊天记录。怀疑泄露时停止并重新启动 API，旧令牌立即失效。
• API 只监听 127.0.0.1，局域网和互联网上的其他设备无法直接访问。Host 校验主要用来挡住浏览器和误用，不能代替访问控制；不要用端口转发或反向代理把它暴露出去。
• 这台电脑上的其他程序拿到令牌后同样可以调用 API。只在可信的电脑上启用，用完点击“停止 API”。
• “自动化 API”窗口中的“紧急停止”会停止 API，并关闭本次通过 API 启动、仍在运行的环境。
• Prism 执行的每个请求都会写入本机审计日志 vault/logs/automation-audit.jsonl（在 Prism 数据目录中），记录时间、动作、结果、请求 ID、环境 ID 和失败原因，不记录令牌、请求内容和网页内容。被请求规则拒绝的请求和 GET /v1/status 不会记录。

常见问题

可以在网页或浏览器扩展里调用吗？

不可以。浏览器发出的请求会带 Origin 请求头，API 会拒绝。请在终端、脚本或本地程序中调用。

为什么用 localhost 会返回 403？

API 要求 Host 请求头与 API 地址中的 127.0.0.1 和端口完全一致，localhost 会被拒绝。请把地址中的主机名写成 127.0.0.1。

“自动化 API”窗口显示运行中，却没有令牌怎么办？

开启 MCP 后，Prism 会自动启动 API 与 MCP 共用的本地服务，此时窗口只显示地址。令牌只在点击“启动本地 API”成功时显示一次：先点击“停止 API”，再点击“启动本地 API”，即可得到新令牌。停止期间 MCP 连接也会中断。

重启 Prism 后还能用原来的令牌吗？

不能。每次启动 API 都会生成新的端口和令牌；停止 API 或退出 Prism 后，旧令牌失效。

能用 API 修改或删除环境吗？

不能。API 可以创建、查询、启动和关闭环境；修改配置和删除请在 Prism 界面中操作。

能连接 Puppeteer、Playwright 或 Selenium 吗？

不能。API 不提供调试端口或 WebDriver 地址。需要页面级操作时，可以通过 MCP 让 AI 客户端完成。

可以一次启动很多环境吗？

可以逐个调用启动接口。Prism 依次处理请求，一个环境启动完成后再处理下一个；同时运行的数量取决于电脑的内存和 CPU。

Windows 也能用吗？

可以。macOS 与 Windows 版 Prism Pro 都提供本地 API，接口相同。在 Windows PowerShell 中请使用 curl.exe 或 Invoke-RestMethod。

相关功能与教程