跳到正文

实时画面与会话

实时观看托管浏览器，接管或分享画面，管理你的会话，并让浏览器保持运行，以便稍后重新连接。

实时画面：观看、接管、分享

在仪表盘中点击某个会话，即可查看它的流量去往了哪些站点，并实时观看。点击“Take control”后，你可以亲自在其中点击、输入、滚动、粘贴和导航，例如完成登录，或者处理脚本无法通过的检查。你的脚本在此期间始终保持连接，所以你操作时请先暂停脚本。人工输入也算作活动，因此你正在操作的会话不会因空闲而被关闭。“Share”会生成一个无需账号、任何人都能打开的链接，可设为仅观看或允许控制，有效期为 15 分钟到 4 小时，且最长不超过会话结束的时间。

通过 API：

bash
# a live-view WebSocket for a running session (open it within 60 s)
# binary messages are JPEG frames, text messages are {"url","title","tabs"}
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/live

# with control: the answer says "interactive": true when it was granted
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/live?control=1"

# a share link: control optional, 1 to 240 minutes (default 30)
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"control": false, "minutes": 60}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share

在控制模式下，通过同一个 WebSocket 发送 JSON 文本消息。坐标是你所看到画面的比例值（0 到 1）；其他内容一律忽略。

消息作用
{"t":"mouse","e":"down","x":0.5,"y":0.3,"b":"left","n":1,"m":0}按下（down）、松开（up）或移动（move）；n 为点击次数，m 为修饰键（Alt 1、Ctrl 2、Meta 4、Shift 8）。
{"t":"wheel","x":0.5,"y":0.5,"dx":0,"dy":400}在某一点按像素滚动。
{"t":"key","e":"down","key":"a","code":"KeyA","kc":65,"text":"a"}按键按下或抬起，与键盘实际发送的一致。
{"t":"text","text":"pasted text"}像键盘输入一样插入文本（最多 5000 个字符）。
{"t":"nav","a":"back"}、forward、reload 或 {"t":"nav","a":"go","url":"example.com"}历史前进/后退、重新加载，或打开一个 http(s) 地址。

GET /api/v1/browsers/<id> 的返回中包含 traffic：该会话按字节数排名前 20 的站点。

管理会话

bash
# one session: status, traffic, seconds, cost so far
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# stop it (a running browser closes within about 15 seconds)
curl -X DELETE -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>

# balance + your 20 most recent sessions
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers

# filtered by status and note text, up to 100; page back with before=<a createdAt you got>
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers?status=active,ended&note=shop-de&limit=50"

# label a session (null clears it)
curl -X PATCH -H "authorization: Bearer cc_live_..." -H "content-type: application/json" -d '{"note": "shop-de nightly"}' https://www.clearcotelabs.com/api/v1/browsers/<id>

创建会话时给它加上 note，之后就能在列表和仪表盘中再次找到它。若要在之前某个会话所在的同一台服务器上启动新会话（缓存已预热、同一台机器），请传入那个会话的 worker；该服务器已满时你会收到 503，而不会被分配到另一台服务器。

当你关闭浏览器或断开连接，或者达到下文的某项限制时，会话也会结束。对于还没有人连接过的会话，停止请求会立即结束它；正在运行的浏览器则会在一个上报周期（约 15 秒）内由其所在服务器关闭。GET 返回：

json
{
  "id": "bs_…",
  "status": "active",                 // see the table below
  "proxy": "managed",                 // or "custom"
  "createdAt": "…", "startedAt": "…", "endedAt": null,
  "endReason": null,                  // set once ended, e.g. "user", "balance", "launch_failed"
  "stopRequested": false,
  "usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
  "traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
  "costEur": 0.0050,
  "pricing": { "eurPerGb": 1, "eurPerHour": 0 }
}
status含义
pendingCreated; nobody has connected yet. Counts towards the concurrency limit until it starts or expires.
activeA browser is running and reporting usage.
lostNo usage report for 5 minutes. Billed up to the last report; a late report puts it back to active.
endedClosed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which.
expiredNobody connected within two minutes of creating it. Never billed.

列表调用 GET /api/v1/browsers 返回 { balanceEur, sessions: [...] }，其中的会话对象与上面相同，按从新到旧排列。

保持浏览器运行与重新连接

默认情况下，客户端断开连接时会话就会结束。如果启动时设置 keepAlive: true，浏览器则会继续运行，并保留其标签页、cookie 和出口 IP，这样之后的脚本（或者在崩溃、合上笔记本之后重新运行的同一个脚本）就能从上次中断的地方继续：

bash
# a new single-use connect URL for a running keepAlive session (connect within two minutes)
curl -X POST -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/connect
  • 保持运行的方法是断开连接：Playwright 的 browser.close()（通过 connectOverCDP 连接时它只会断开连接）、Puppeteer 的 browser.disconnect()，或者直接结束你的进程。
  • 结束会话可以调用 DELETE /api/v1/browsers/<id>，或发送 CDP 命令 Browser.close：Puppeteer 的 browser.close() 会发送它；在 Playwright 中则用 await (await browser.newBrowserCDPSession()).send("Browser.close")。在此之前，它会一直占用你并发上限中的一个名额。
  • 同一时间只允许一个客户端：已有其他客户端接入时，重新连接会被拒绝并返回 409；对启动时未设置 keepAlive 的会话重新连接也是如此。
  • 无人连接期间，各项限制依然有效：idleTimeoutSec（如果你打算稍后回来继续使用这个浏览器，可以调高它，最大 1800）、timeoutSec、maxGb 以及你的余额。保持打开的页面会继续产生后台流量，和其他流量一样计费。