ovoBrowser本地API使用教程

ovoBrowser本地API用於在本機管理瀏覽器環境、分組、標籤、代理、回收站和瀏覽器行程。 介面只監聽127.0.0.1，不需要Token、Bearer Token或x-api-key。

1.啟動管道

案頭端自動啟動

帳號登入成功後，本地API會自動啟動，並保存當前埠。 下次保存會話恢復成功後也會自動啟動。 默認地址：

http://127.0.0.1:50325

實際埠以用戶端「API & MCP」頁面為准。 Google、GitHub、 帳號密碼登入和邀請注册最終都會建立同一種登入會話，所以成功進入帳號後都會啟動本地API。

如果在用戶端中手動停止服務，當前埠會立即關閉； 下次登入或會話恢復成功時仍會自動啟動。

CLI模式

先在案頭端成功登入一次並保持登入狀態，然後執行：

& "C:\Program Files\ovoBrowser\ovoBrowser.exe" --cli --api-port 50325

程式路徑以實際安裝位置為准。--api-port可省略，省略時使用已保存埠。 CLI複用作業系統安全存儲中的帳號會話，不接收命令列帳號密碼或Token。

“保持登入狀態”表示沒有在案頭端點擊登出，而且保存會話仍然有效。 若已登出、會話過期或應用數據被清除，需要重新打開案頭端登入； Google/GitHub登入也在案頭端完成。

2.調用規則

• 所有介面都使用POST，參數放在JSON Body中。

• 請求頭使用Content-Type: application/json。

• 環境定位推薦使用id；多數介面也支持seq環境序號。

• 分頁參數page從0開始，pageSize範圍為1-100。

• 帳號、Cookie、2FA金鑰和代理密碼屬於敏感資訊，不要寫入公共日誌。

成功響應：

{"success":true,"data":{}}

失敗響應：

{"success":false,"msg":"失败原因"}

3.介面總覽

4.健康檢查

curl --location 'http://127.0.0.1:50325/health' \
  --header 'Content-Type: application/json' \
  --data '{}'

返回data.running=true表示埠已經啟動。 再調用環境清單可確認帳號會話和工作區已經恢復。

5.分組API

分組用於單選歸類：一個環境最多屬於一個分組，通過groupId綁定。

分組清單

curl --location 'http://127.0.0.1:50325/group/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

data.list是分組數組，_count.profiles是分組中的環境數量。

新增分組

curl --location 'http://127.0.0.1:50325/group/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"电商账号","color":"#3478F6"}'

編輯分組

id和groupId都可以定位分組。 除定位欄位外，只傳需要變化的欄位。

curl --location 'http://127.0.0.1:50325/group/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID","name":"重要电商账号","color":"#16A34A"}'

删除分組

curl --location 'http://127.0.0.1:50325/group/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"分组ID"}'

删除分組不會删除環境，原分組下的環境會變成未分組。 系統默認分組不能删除。

6.標籤API

標籤用於多選標記：一個環境最多綁定20個標籤，通過tagIds數組綁定。

標籤清單

curl --location 'http://127.0.0.1:50325/tag/list' \
  --header 'Content-Type: application/json' \
  --data '{}'

新增標籤

curl --location 'http://127.0.0.1:50325/tag/create' \
  --header 'Content-Type: application/json' \
  --data '{"name":"高优先级","color":"#F97316"}'

編輯標籤

curl --location 'http://127.0.0.1:50325/tag/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID","name":"VIP","color":"#A855F7"}'

删除標籤

curl --location 'http://127.0.0.1:50325/tag/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"标签ID"}'

删除標籤會解除它與所有環境的關聯，但不會删除環境。

7.代理API

環境可以先創建可複用代理再傳proxyId，也可以在創建或更新環境時直接傳proxy。兩種方式不能同時使用。

代理清單

curl --location 'http://127.0.0.1:50325/proxy/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":""}'

響應返回當前代理密碼password和hasPassword，不會返回服務端密文。

新增代理

curl --location 'http://127.0.0.1:50325/proxy/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"Tokyo Proxy",
    "protocol":"SOCKS5",
    "host":"proxy.example.com",
    "port":1080,
    "username":"proxy-user",
    "password":"proxy-password"
  }'

編輯代理

id和proxyId都可以定位代理。 省略password保留原密碼，傳null清除密碼。

curl --location 'http://127.0.0.1:50325/proxy/update' \
  --header 'Content-Type: application/json' \
  --data '{"id":"代理ID","host":"new-proxy.example.com","port":1080,"password":"new-password"}'

修改協定、主機、埠、用戶名或密碼後，檢測狀態會重置為UNCHECKED。

8.創建環境

完整欄位說明

accounts每一項：

內聯proxy：

完整創建示例

curl --location 'http://127.0.0.1:50325/browser/create' \
  --header 'Content-Type: application/json' \
  --data '{
    "name":"完整环境示例",
    "platform":"windows",
    "remark":"通过本地 API 创建",
    "groupId":"分组ID",
    "tagIds":["标签ID1","标签ID2"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"account-password",
        "totpSecret":null,
        "openOnStart":true,
        "remark":"主账号"
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"cookie-value",
        "domain":".example.com",
        "path":"/",
        "secure":true,
        "httpOnly":true,
        "sameSite":"Lax"
      }
    ],
    "startupUrls":[
      "https://example.com/login",
      "https://example.com/dashboard"
    ],
    "fingerprint":{
      "timezone":"Asia/Shanghai",
      "acceptLanguage":"zh-CN,zh,en"
    },
    "proxy":{
      "type":"HTTP",
      "host":"proxy.example.com",
      "port":8080,
      "username":"proxy-user",
      "password":"proxy-password"
    }
  }'

使用已有代理時，删除proxy整段，改傳“proxyId”：“已有代理ID”。不使用代理時，proxy和proxyId都不要傳。

Cookie格式

推薦使用cookies直接傳JSON數組。 Cookie常用欄位：name、value、domain、path、secure、httpOnly、expirationDate、sameSite。

如果使用cookieData，它必須是字串，可放瀏覽器擴展匯出的JSON文字、 Netscapecookies.txt，或請求頭文字a=1; b=2。

沒有domain的Cookie啟動時只能根據首個啟動網址推斷功能變數名稱，建議顯式填寫domain。

9.更新環境

更新介面只修改發送的欄位； 省略欄位保持不變。 定位支持id、profileId、seq、serialNumber、serial_number。

覆蓋規則：

• accounts整組覆蓋，[]清空全部帳號；

• tagIds整組覆蓋，[]清空全部標籤；

• cookies或cookieData替換Cookie，null清空；

• startupUrls替換全部啟動網址，[]清空；

• groupId:null解除分組；

• proxy:null或proxyId:null解除代理。

curl --location 'http://127.0.0.1:50325/browser/update' \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"环境ID",
    "name":"更新后的环境",
    "remark":"完整更新示例",
    "groupId":"分组ID",
    "tagIds":["标签ID"],
    "accounts":[
      {
        "platform":"google",
        "username":"[email protected]",
        "password":"new-password",
        "openOnStart":false
      }
    ],
    "cookies":[
      {
        "name":"session_id",
        "value":"new-cookie-value",
        "domain":".example.com",
        "path":"/"
      }
    ],
    "startupUrls":["https://example.com/dashboard"],
    "proxyId":"已有代理ID"
  }'

修改運行中環境的代理、 Cookie、 啟動網址或指紋後，先關閉環境，再重新打開。

10.査詢環境

環境清單

curl --location 'http://127.0.0.1:50325/browser/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"name":"","groupId":"分组ID","tagId":"标签ID"}'

不需要的篩選欄位直接删除。data.list是環境數組，data.totalNum是總數； 環境對象包含group和tags。

環境詳情

curl --location 'http://127.0.0.1:50325/browser/detail' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

詳情返回group、tags、fingerprint、proxy、accountCount、hasCookieData。環境所有者還會收到cookieData。

11.删除、回收站和徹底删除

删除環境到回收站

curl --location 'http://127.0.0.1:50325/browser/delete' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

如果環境正在運行，會先關閉瀏覽器，再移入回收站。 此操作可恢復。

回收站清單

curl --location 'http://127.0.0.1:50325/browser/recycle/list' \
  --header 'Content-Type: application/json' \
  --data '{"page":0,"pageSize":10,"search":"","sort":"desc"}'

清單中的環境id可用於恢復或徹底删除。

恢復環境

curl --location 'http://127.0.0.1:50325/browser/restore' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

恢復必須使用環境ID，不能只傳環境序號。

徹底删除環境

單個：

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"id":"回收站环境ID"}'

批量：

curl --location 'http://127.0.0.1:50325/browser/delete/permanent' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

ids最多500個。 只會删除已經在回收站中的環境，data.purged是實際删除數量。

徹底删除不可恢復，環境配寘、帳號和Cookie都會永久删除。

12.打開、査詢和關閉環境

打開環境

curl --location 'http://127.0.0.1:50325/browser/open' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID","headless":false}'

headless必須是JSON布林值。 響應返回pid、ws、http、headless；ws可交給Playwright或Puppeteer。

運行狀態

curl --location 'http://127.0.0.1:50325/browser/active' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

無參數調用/browser/active時返回全部運行環境。 運行清單：

curl --location 'http://127.0.0.1:50325/browser/running' \
  --header 'Content-Type: application/json' \
  --data '{}'

PID和CDP埠

curl --location 'http://127.0.0.1:50325/browser/pids' \
  --header 'Content-Type: application/json' \
  --data '{"ids":["环境ID1","环境ID2"]}'

curl --location 'http://127.0.0.1:50325/browser/pids/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

curl --location 'http://127.0.0.1:50325/browser/ports' \
  --header 'Content-Type: application/json' \
  --data '{}'

關閉環境

curl --location 'http://127.0.0.1:50325/browser/close' \
  --header 'Content-Type: application/json' \
  --data '{"id":"环境ID"}'

關閉全部：

curl --location 'http://127.0.0.1:50325/browser/close/all' \
  --header 'Content-Type: application/json' \
  --data '{}'

關閉全部會影響當前所有工作視窗，執行前請保存頁面內容。

13. Postman使用

導入幫助中心提供的https://www.postman.com/ovo-desktop-api/workspace/ovodesktop-api-example/collection/57777046-8485fa5f-3e60-4da9-8b59-538ae4703339?action=share&source=copy-link&creator=57777046https://www.postman.com/ovo-desktop-api/workspace/ovodesktop-api-example/collection/57777046-8485fa5f-3e60-4da9-8b59-538ae4703339?action=share&source=copy-link&creator=57777046：

1. 在集合Variables中確認baseUrl；

2. 運行「健康檢查」；

3. 運行「環境清單」確認會話已恢復；

4. 每個請求都帶用途、欄位說明、完整JSON Body和cURL示例；

5. 如需完整演示，按資料夾順序運行即可，無需理解環境序號或手工維護複雜變數；

6. 執行「徹底删除環境」前，確認目標是允許永久删除的測試環境。

14.常見錯誤