实时画面与会话
实时观看托管浏览器,接管或分享画面,管理你的会话,并让浏览器保持运行,以便稍后重新连接。
本页的每个请求都可以直接在页面上发送。登录后,示例会带上你的 API 密钥;点击“发送”会发起真实调用并显示真实响应,你可以修改某个字段,看看它会带来什么变化。
先启动一个浏览器来试用
下文的大部分请求都需要一个正在运行的浏览器。可以在这里启动一个:它是普通会话,与其他会话一样计费(每 GB €1.00,从你的余额中扣除);这个会话在连续 5 分钟没有收到命令,或总时长达到 15 分钟后会自动结束。
POST 启动浏览器
响应中包含会话的 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 打开实时画面
为正在运行的会话打开实时画面 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 分享实时画面
生成一个无需账号、任何人都能打开的链接:可选择是否允许控制,有效期 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", | 按下(down)、松开(up)或移动(move);n 为点击次数,m 为修饰键(Alt 1、Ctrl 2、Meta 4、Shift 8)。 |
{"t":"wheel", | 在某一点按像素滚动。 |
{"t":"key", | 按键按下或抬起,与键盘实际发送的一致。 |
{"t":"text", | 像键盘输入一样插入文本(最多 5000 个字符)。 |
{"t":"nav",、forward、reload 或 {"t":"nav", | 历史前进/后退、重新加载,或打开一个 http(s) 地址。 |
GET /api/v1/browsers/<id> 的返回中包含 traffic:该会话按字节数排名前 20 的站点。
管理会话
GET 单个会话
该会话的状态、流量、秒数和截至目前的费用。各字段的说明见这些请求的下方。
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
GET 你的会话
你的余额和会话,按从新到旧排列:默认 20 个,通过 limit 最多可取 100 个。可按状态和备注文本筛选;要查看更早的会话,请把 before 设为你拿到的最后一个会话的 createdAt。在某一行点击“使用”,即可在其他请求中使用该会话。
curl 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..."
PATCH 为会话添加备注
设置或修改 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 停止会话
还没有人连接过的会话会立即结束;正在运行的浏览器则会在一个上报周期(约 15 秒)内由其所在服务器关闭。
curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
创建会话时给它加上 note,之后就能在列表和仪表盘中再次找到它。若要在之前某个会话所在的同一台服务器上启动新会话(缓存已预热、同一台机器),请传入那个会话的 worker;该服务器已满或离线时,会话会在另一台服务器上启动,并在 warnings 中说明。
当你关闭浏览器或断开连接,或者达到下文的某项限制时,会话也会结束。对于还没有人连接过的会话,停止请求会立即结束它;正在运行的浏览器则会在一个上报周期(约 15 秒)内由其所在服务器关闭。GET 返回:
{
"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 | 含义 |
|---|---|
pending | Created; 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). |
active | A browser is running and reporting usage. |
lost | No 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. |
ended | Closed: 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. |
expired | Nobody connected before expiresAt (45 seconds after creating it). Never billed. |
queue 表示正在启动的浏览器在其服务器的启动队列中所处的位置,这样繁忙时段看到的是排队位置,而不是一次缓慢的连接。创建会话的响应中也带有一个估算值: "queue": { "position": 3, "etaSec": 6 },即如果你现在连接,浏览器会排在哪里(服务器未报告队列时,两者均为 null)。
| queue 字段 | 含义 |
|---|---|
state | waiting_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. |
position | 1-based place in the server's waiting list while queued, else null. |
ahead | How many browsers start before this one: position - 1 while queued, 0 while launching, else null. |
etaSec | Estimated 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. |
updatedAt | When 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 重新连接
为正在运行的 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以及你的余额。保持打开的页面会继续产生后台流量,和其他流量一样计费。