本地 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"
  }
}

API 不會傳回代理位址與認證資訊、指紋參數、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 小時內最多保留 1,000 個帶識別碼的請求，這個上限與 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 小時內 1,000 筆記錄的上限。

安全建議

• 權杖相當於這臺電腦上管理環境的鑰匙：不要寫進程式碼儲存庫、記錄檔或聊天記錄。懷疑外洩時，請停止並重新啟動 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。

相關功能與教學