BrowserIP API v1

Base URL: https://browserip.com · 所有 REST 接口返回 JSON · CDP 走 wss://

Quickstart · 5 steps

快速开始

第 0 步 · 先验证，不用安装：下面这条 curl 就是第一步，跑通、拿到 cdp_url 再装 SDK 也不迟。完整流程：拿 Key → curl 验证 → 装 SDK（Python / Node.js / browser-use）→ CDP 连上去干活 → DELETE 关会话停计费。

不用装任何东西，一条 curl 就能验证你的 Key 并启动一个云浏览器：

export BIP_KEY="bip_你的key"

# 创建会话（返回 cdp_url）
curl -X POST https://browserip.com/api/sessions \
  -H "Authorization: Bearer $BIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region": "singapore"}'

# 用完关闭（停止计费）
curl -X DELETE https://browserip.com/api/sessions/<id> \
  -H "Authorization: Bearer $BIP_KEY"

💡 401 表示 Key 错了或没 export。402 表示余额不足，先去控制台充值。

认证

两种方式（二选一）：

方式	用法	适用场景
API Key 推荐	`Authorization: Bearer bip_...`	代码 / 脚本 / CI
Cookie	浏览器登录后自动携带	控制台手动操作

在控制台 → API Keys 生成 Key（bip_ + 48 位 hex）。完整 Key 只显示一次，丢了重新生成。

三种接入方式

	REST API	一次性 API（v1）	CDP 直连
是什么	HTTPS 接口，管会话生命周期	HTTPS 接口，一次调用办一件事	WebSocket，直连浏览器内核
用来干嘛	创建 / 查询 / 关闭会话、查余额	截图、抓正文、转 PDF、跑一段 JS	完全操控页面：点击、输入、多步流程
工具	curl / requests / fetch	curl / requests / fetch	Playwright / Puppeteer / browser-use

典型流程：简单任务直接调一次性 API；复杂多步流程用 REST 创建会话拿到 cdp_url → CDP 连上去干活 → REST 关闭会话停止计费。

会话 API

POST/api/sessions

创建一个浏览器会话。按需分配，20 分钟无操作自动回收。

参数	类型	必填	说明
`region`	string	可选	`singapore` / `us-west` / `japan`。不填则自动选择延迟最低的区域。
`proxy`	string	可选	自配代理：`http://user:pass@host:port` 或 `socks5://host:port`。不填则用 worker 默认出口 IP。

返回 200：

{
  "session": {
    "id": "8f5d079a-45b4-41a9-bf51-4a13f3878445",
    "token": "71a510cb...",
    "cdp_url": "https://browserip.com/s/8f5d079a.../71a510cb...",
    "view_url": "/view/8f5d079a.../71a510cb...",
    "status": "starting",
    "region": "singapore",
    "created_at": "2026-10-19T04:30:00Z"
  }
}

左侧参数表 + 右侧请求示例为两栏阅读：左看参数含义，右抄请求；返回状态用上面标签切换，错误含义见文末错误码表。

GET/api/sessions

列出你的会话（最近 50 个，含已关闭）。

GET/api/sessions/:id

查询单个会话。轮询此接口直到 status=ready 即可连接 CDP。

status	说明
`starting`	分配中，通常 5–15 秒
`ready`	可用，CDP 可连
`done`	已关闭
`failed`	启动失败，看 `fail_reason`

DELETE/api/sessions/:id

关闭会话，浏览器立即销毁，停止计费。

返回： {"billed_credits": 2, "duration_sec": 95}

GET/api/auth/me

查询当前用户与余额。

返回： {"user": {"email": "...", "credits": 1497.1, "is_admin": false}}

CDP 直连

每个会话的 cdp_url 是标准 Chrome DevTools 协议地址。把 https:// 换成 wss:// 即可连接。

from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(
            "wss://browserip.com/s/<id>/<token>")
        page = browser.contexts[0].pages[0]
        await page.goto("https://example.com")
        print(await page.title())
        await browser.close()  # 别忘了关，省 credits

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://browserip.com/s/<id>/<token>"
});
const page = (await browser.pages())[0];
await page.goto('https://example.com');
console.log(await page.title());
await browser.disconnect();

from browser_use import Agent, BrowserSession

session = BrowserSession(
    cdp_url="https://browserip.com/s/<id>/<token>")
agent = Agent(task="...", browser_session=session)
result = await agent.run()

可视化调试：浏览器打开 view_url 实时看画面、手动操作，无需登录。

一次性 API（v1）

不想自己管 CDP 连接？这四个端点一次调用完成一次浏览器任务：服务端自动拉起临时浏览器、执行、返回结果、销毁会话。按正常会话计费（1 分钟起）。Body 通用参数：url（必填，http/https 公网地址）、region（可选）、wait_ms（可选，加载后额外等待，默认 800ms）。内网地址会被拒绝。

POST/api/v1/screenshot

整页/视口截图。Body: {"url": "...", "width": 1280, "height": 800, "fullPage": true}。返回 image/png 二进制。

POST/api/v1/scrape

抓取页面标题与正文（JS 渲染后）。Body: {"url": "..."}。返回 {"url","title","text","session_id"}。

POST/api/v1/pdf

页面转 PDF。Body: {"url": "..."}。返回 application/pdf 二进制。

POST/api/v1/evaluate

在页面里执行一段 JS 并返回结果（支持 async）。Body: {"url": "...", "script": "document.title"}。返回 {"result": ..., "session_id": "..."}。JS 报错返回 422 js_error。

curl -X POST https://browserip.com/api/v1/scrape \
  -H "Authorization: Bearer bip_<你的key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

API Keys

POST/api/keys

生成新 Key。Body: {"name": "ci-server"}（可选）。完整 Key 只显示一次。

GET/api/keys

列出 Keys（仅显示前缀）。

DELETE/api/keys/:id

吊销 Key，立即失效。

错误码

HTTP	error	说明
`401`	`unauthorized`	没带 Key，或 Key 错误/已吊销
`402`	`insufficient_credits`	余额不足，先充值
`404`	`not_found`	会话不存在或已关闭
`429`	`no_capacity`	无空闲浏览器，稍后重试
`429`	`too_many_sessions`	达到并发上限（默认 3）
`500`	`internal_error`	服务端异常，带时间找我们

计费

$0.10 / 小时，按分钟向上取整（1 分 01 秒按 2 分钟）
ready 后开始计费，DELETE 或 20 分钟闲置后停止
余额 ≤ 0 时会话立即关闭
注册送 1 credit（= 6 分钟）

缺端点、SDK、webhook？去控制台生成你的第一个 Key 开始试。

本页有帮助吗？