API 参考

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

身份验证

所有 API 端点都需要 Bearer 令牌身份验证

Authorization: Bearer your-user-token-here
GET/api/quota

GET /api/quota

在启动作业之前检查剩余配额

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

Example Request:

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

Example Response:

{
  "remainingQuota": 7650,
  "pricing": {
    "baseRate": 1,
    "multiplier": 1.0,
    "effectiveRate": 1.0,
    "breakdown": {
      "base": 1.0,
      "maxSessions": 1,
      "sessionMultiplier": 1.0,
      "userDataMax": 5,
      "userDataPremium": 0,
      "hasLiveURLAccess": false,
      "liveURLPremium": 0
    }
  }
}
GET/api/usage

GET /api/usage

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

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

Example Request:

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

Example Response:

{
  "totalSessions": 142,
  "totalMinutes": 2350,
  "activeSessions": 1
}
GET/api/history

GET /api/history

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

可选的 start 和 end 查询参数（ISO 8601 时间戳）

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

Example Request:

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

Example Response:

{
  "sessions": [
    {
      "id": 1,
      "startedAt": "2025-01-15T10:30:00Z",
      "endedAt": "2025-01-15T10:33:25Z",
      "durationMinutes": 3,
      "quotaConsumed": 3,
      "disconnectReason": "client_closed"
    }
  ],
  "total": 1
}
POST/api/user-data

POST /api/user-data

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

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

Example Request:

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

Example Response:

{
  "id": "udd_abc123xyz789defg",
  "createdAt": "2025-01-15T10:30:00Z"
}
GET/api/user-data

GET /api/user-data

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

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

Example Request:

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

Example Response:

{
  "items": [
    {
      "id": "udd_abc123xyz789defg",
      "createdAt": "2025-01-15T10:30:00Z",
      "lastUsedAt": "2025-01-15T12:45:00Z",
      "isLocked": false
    }
  ],
  "total": 1,
  "quota": {
    "used": 1,
    "max": 5,
    "canCreate": true
  }
}
DELETE/api/user-data/:id

DELETE /api/user-data/:id

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

Response: 返回成功状态

Example Request:

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

Example Response:

{
  "success": true
}

计费模型

按使用量计费：1 分钟浏览器会话时间 = 1 配额单位

断开原因

client_closed— 客户端调用了 browser.close()
client_disconnected— WebSocket 连接意外关闭
server_closed— 浏览器服务器关闭了连接
insufficient_balance— 会话期间配额耗尽
socket_timeout— 5 分钟内没有数据传输
tcp_error— 网络错误