Documentation

API 参考

用于配额管理、使用跟踪和会话历史的 REST API 端点

Quick Start

Connect your existing Puppeteer, Playwright, or CDP automation to BotCloud by swapping your WebSocket endpoint to wss://cloud.bots.win. No code rewrites — just one line change.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

认证

所有 API 端点都需要 Bearer 令牌认证

# All API endpoints require Bearer token authentication
curl -H "Authorization: Bearer your-user-token-here" \
  https://cloud.bots.win/api/quota

GET /api/quota

在启动工作前检查剩余配额

GET/api/quota

Response: 返回总配额、已用配额、剩余配额和使用百分比

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/quota

GET /api/usage

获取用于报告和成本分析的使用统计

GET/api/usage

Response: 返回总会话数、总分钟数和活跃会话计数

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/usage

GET /api/history

检索会话历史用于审计跟踪

GET/api/history

Parameters: 可选的开始和结束查询参数（ISO 8601 时间戳）

Response: 返回会话对象数组，包含持续时间和断开原因

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/history

POST /api/user-data

创建新的用户数据容器用于持久浏览器状态（Cookie、localStorage 等）

POST/api/user-data

Response: 返回创建的用户数据 ID 和时间戳

curl -X POST -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

GET /api/user-data

列出经过认证用户的所有用户数据容器

GET/api/user-data

Response: 返回用户数据对象数组及配额信息

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

DELETE /api/user-data/:id

删除用户数据容器并释放配额

DELETE/api/user-data/:id

Response: 返回成功状态

curl -X DELETE -H "Authorization: Bearer your-token" \
  https://cloud.bots.win/api/user-data/udd_abc123xyz789defg

Framework Integration

Puppeteer, PuppeteerSharp, Playwright (Node.js / Python / .NET), raw CDP, Go (chromedp / rod), Java (native WebSocket), and Ruby (Ferrum) all work without code rewrites. Swap wss://cloud.bots.win as your endpoint and pass your token, proxy, and device type as query parameters.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

计费模式

订阅方案包含每月浏览器小时数。超出后,额外用量按方案 overage 费率从预付余额中扣除。

连接错误

这些错误发生在连接建立阶段 — 会话尚未创建,因此不会出现在 /api/history 中。请根据 HTTP 状态码和响应体中的消息进行处理。

HTTP Status	Cause
400	缺失 --proxy-server 查询参数,或格式不正确
401	缺失或无效的 token
401	订阅未激活(未订阅、已失效、或周期已过期)
401	试用 token 已过期或配额已用完
403	账户余额不足 — 订阅小时数已用尽且余额为零
429	试用账户同时只能有 1 个活跃会话

断开原因

会话建立之后,最终会以下列原因之一结束,并记录在 /api/history 中。可基于这些代码做错误处理和审计。

Code	Description
socket_close	客户端关闭了连接(例如 browser.close() 或进程退出)— 最常见,正常结束
idle_timeout	客户端长时间无活动,会话被网关结束
browser_close_graceful	浏览器自行关闭(例如页面内调用 window.close())
trial_exhausted	会话期间试用配额用完
primary_blocked:Insufficient balance	会话进行中账户余额不足,网关关闭了会话
primary_blocked:Subscription lapsed or expired	会话进行中订阅过期或失效
browser_disconnect	浏览器与网关连接中断 — 可重试
browser_crash	浏览器进程崩溃 — 可重试
gateway_crash	网关重启,会话被终止 — 可重试
socket_error	网络层错误(TCP reset 或异常断开)