跳到正文

实时画面与会话

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

本页的每个请求都可以直接在页面上发送。登录后,示例会带上你的 API 密钥;点击“发送”会发起真实调用并显示真实响应,你可以修改某个字段,看看它会带来什么变化。

先启动一个浏览器来试用

下文的大部分请求都需要一个正在运行的浏览器。可以在这里启动一个:它是普通会话,与其他会话一样计费(每 GB €1.00,从你的余额中扣除);这个会话在连续 5 分钟没有收到命令,或总时长达到 15 分钟后会自动结束。

POST 启动浏览器

/api/v1/browsers

响应中包含会话的 id 和一个一次性的 connectUrl。客户端连接到该 URL 后会话才会开始(在此之前状态为 pending,45 秒后过期)。点击“连接”,文档会像你的 Playwright 或 Puppeteer 脚本那样连接、读取标签页,然后断开;设置了 keepAlive 时,浏览器会继续运行,供下面的请求使用。

示例
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"keepAlive":true,"url":"https://example.com","idleTimeoutSec":300,"timeoutSec":900,"note":"docs"}'

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

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

通过 API:

GET 打开实时画面

/api/v1/browsers/{id}/live

为正在运行的会话打开实时画面 WebSocket(需在 60 秒内打开)。二进制消息是 JPEG 帧,文本消息是 {"url","title","tabs"}。带上 control=1 时,如果获得了控制权,响应中会包含 "interactive": true。点击“在此观看”即可在本页打开画面。时间线上的每个事件也会在发生时立即以 {"ev": …} 的形式送达(参见录制)。

示例
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \
  -H "authorization: Bearer cc_live_..."

POST 分享实时画面

/api/v1/browsers/{id}/share

生成一个无需账号、任何人都能打开的链接:可选择是否允许控制,有效期 1 到 240 分钟(默认 30),且最长不超过会话结束的时间。允许控制的链接请像 API 密钥一样妥善保管。使用 replay: true(且不带控制)时,它会变成观看 + 回放链接:会话运行时实时观看,结束后观看其回放,有效期 1 到 20160 分钟(默认 10080,即 7 天)。

示例
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/share' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"control":false,"minutes":60}'

在控制模式下,通过同一个 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 的站点。

管理会话

GET 单个会话

/api/v1/browsers/{id}

该会话的状态、流量、秒数和截至目前的费用。各字段的说明见这些请求的下方。

curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..."

GET 你的会话

/api/v1/browsers

你的余额和会话,按从新到旧排列:默认 20 个,通过 limit 最多可取 100 个。可按状态和备注文本筛选;要查看更早的会话,请把 before 设为你拿到的最后一个会话的 createdAt。在某一行点击“使用”,即可在其他请求中使用该会话。

示例
curl 'https://www.clearcotelabs.com/api/v1/browsers' \
  -H "authorization: Bearer cc_live_..."

PATCH 为会话添加备注

/api/v1/browsers/{id}

设置或修改 note(最多 256 个字符);设为 null 即可清除。

示例
curl -X PATCH 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..." \
  -H "content-type: application/json" \
  -d '{"note":"shop-de nightly"}'

DELETE 停止会话

/api/v1/browsers/{id}

还没有人连接过的会话会立即结束;正在运行的浏览器则会在一个上报周期(约 15 秒)内由其所在服务器关闭。

curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \
  -H "authorization: Bearer cc_live_..."

创建会话时给它加上 note,之后就能在列表和仪表盘中再次找到它。若要在之前某个会话所在的同一台服务器上启动新会话(缓存已预热、同一台机器),请传入那个会话的 worker;该服务器已满或离线时,会话会在另一台服务器上启动,并在 warnings 中说明。

当你关闭浏览器或断开连接,或者达到下文的某项限制时,会话也会结束。对于还没有人连接过的会话,停止请求会立即结束它;正在运行的浏览器则会在一个上报周期(约 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 },
  "queue": { "state": null, "position": null, "ahead": null, "etaSec": null, "updatedAt": "…" } // see below
}
status含义
pendingCreated; nobody has connected yet. Counts towards the concurrency limit until it starts or expires (45 seconds after it was created; a run waits for its server instead).
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. If none comes, it ends an hour after the longest a session may last (see Limits and errors): status ended, endReason worker_silent. If the server that ran it restarted, it ends as soon as that server is back: endReason worker_restarted, billed up to the last report.
endedClosed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which. A launch its geo identity refused (geoIdentity strict) ends with endReason geo_refused:<code>, e.g. geo_refused:GEO_PROXY_COUNTRY_TIMEZONE_MISMATCH, and is not billed.
expiredNobody connected before expiresAt (45 seconds after creating it). Never billed.

queue 表示正在启动的浏览器在其服务器的启动队列中所处的位置,这样繁忙时段看到的是排队位置,而不是一次缓慢的连接。创建会话的响应中也带有一个估算值: "queue": { "position": 3, "etaSec": 6 },即如果你现在连接,浏览器会排在哪里(服务器未报告队列时,两者均为 null)。

queue 字段含义
statewaiting_for_client: created, nobody has connected yet. queued: you connected and the browser waits for a launch slot on its server. launching: it is starting now. null: running, ended, or the server reported no queue in the last 30 seconds.
position1-based place in the server's waiting list while queued, else null.
aheadHow many browsers start before this one: position - 1 while queued, 0 while launching, else null.
etaSecEstimated seconds until it starts while queued: the browsers ahead, launched as many at a time as the server allows, at its average launch time. Else null.
updatedAtWhen the server last reported its queue (ISO time), or null when it has not in the last 30 seconds.

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

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

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

POST 重新连接

/api/v1/browsers/{id}/connect

为正在运行的 keepAlive 会话生成一个新的一次性连接 URL(需在 45 秒内连接)。点击“连接”会在本页重新连上这个浏览器,所有标签页原样保留。

curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \
  -H "authorization: Bearer cc_live_..."
  • 保持运行的方法是断开连接: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 以及你的余额。保持打开的页面会继续产生后台流量,和其他流量一样计费。