Hivebrowser
API 参考

会话

创建、列出、查询与停止托管浏览器会话。

适用需要一个运行中的浏览器

JavaScript 渲染、登录流程、截图或 Playwright 自动化需要真实会话。

控制明确超时并主动停止

设置 timeoutSec，关闭浏览器客户端，并在任务结束后停止会话。

排查保留运行证据

保存会话 ID，并用实时预览、截图、日志和回放定位失败运行。

调用边界

职责
创建运行时与连接入口

创建运行时、返回 CDP connectUrl，暴露调试证据。

生产
默认显式收口

保存会话 ID、设置 timeoutSec，任务结束主动停止。

接管
按需使用 keepAlive

只在人审或后续流程接管浏览器时使用；生命周期见会话概念页。

列出会话

GET/v1/sessions查看接口细节收起接口细节
GET/v1/sessions

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions", {  headers: {    "Authorization": "Bearer <token>"  }});
响应 200

会话列表

响应示例
{
  "data": {
    "items": [
      {
        "id": "string",
        "teamId": "string",
        "status": "PENDING",
        "closeReason": "USER_REQUEST",
        "browserPlatform": "WINDOWS",
        "browserVersion": "string",
        "region": "string",
        "runnerId": "string",
        "profileId": "string",
        "endpoints": {
          "connectUrl": "http://example.com",
          "wsEndpoint": "http://example.com",
          "liveUrl": "http://example.com",
          "webdriverUrl": "http://example.com",
          "computerActionUrl": "http://example.com"
        },
        "proxy": {
          "server": "string",
          "username": "string",
          "password": "string",
          "bypass": [
            "string"
          ]
        },
        "viewport": {
          "width": 1,
          "height": 1,
          "deviceScaleFactor": 0
        },
        "timeoutSec": 0,
        "keepAlive": true,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "startedAt": "2019-08-24T14:15:22Z",
        "closedAt": "2019-08-24T14:15:22Z",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "total": 0,
    "page": 1,
    "pageSize": 0
  }
}
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}

创建会话

POST/v1/sessions查看接口细节收起接口细节
POST/v1/sessions

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

请求体

application/json必填
browserPlatform字符串

浏览器仿真的目标平台

可选值: "WINDOWS" | "MACOS" | "ANDROID"
browserVersion字符串

指定要使用的浏览器版本

最小长度: 1
region字符串

会话调度的首选区域

最小长度: 1
profile对象

要附加到此会话的浏览器档案

查看属性
profileId必填字符串

要附加的浏览器档案 ID

最小长度: 1
mode字符串

附加浏览器档案的访问模式

默认: "READ_ONLY"可选值: "READ_ONLY" | "READ_WRITE"
persistChanges布尔值

会话关闭时是否将变更写回浏览器档案

默认: false
proxy对象

此会话的代理配置

查看属性
server必填字符串

代理服务器 URL（例如 http://proxy.example.com:8080）

最小长度: 1
username字符串

代理鉴权用户名

最小长度: 1
password字符串

代理鉴权密码

最小长度: 1
bypass数组<字符串>

不走代理的主机列表

viewport对象

浏览器视口尺寸

查看属性
width必填整数

视口宽度（像素）

最小值: 1
height必填整数

视口高度（像素）

最小值: 1
deviceScaleFactor数字

设备缩放因子（DPR）

timeoutSec整数

会话超时时长（秒，最高 24 小时）

最小值: 1最大值: 86400
keepAlive布尔值

客户端断开后保持会话存活

默认: false
metadata对象

会话的自定义键值元数据

查看属性
[key: string]unknown
cURL
curl -X POST "https://api.hivebrowser.ai/v1/sessions" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{    "browserPlatform": "WINDOWS",    "browserVersion": "string",    "region": "string",    "profile": {      "profileId": "string",      "mode": "READ_ONLY",      "persistChanges": false    },    "proxy": {      "server": "string",      "username": "string",      "password": "string",      "bypass": [        "string"      ]    },    "viewport": {      "width": 1,      "height": 1,      "deviceScaleFactor": 0    },    "timeoutSec": 1,    "keepAlive": false,    "metadata": {      "property1": null,      "property2": null    }  }'
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions", {  headers: {    "Authorization": "Bearer <token>"  },  body: JSON.stringify({    "browserPlatform": "WINDOWS",    "browserVersion": "string",    "region": "string",    "profile": {      "profileId": "string",      "mode": "READ_ONLY",      "persistChanges": false    },    "proxy": {      "server": "string",      "username": "string",      "password": "string",      "bypass": [        "string"      ]    },    "viewport": {      "width": 1,      "height": 1,      "deviceScaleFactor": 0    },    "timeoutSec": 1,    "keepAlive": false,    "metadata": {      "property1": null,      "property2": null    }  })});
响应 201

会话已创建

响应示例
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
响应 400

请求载荷无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 429

配额已超出（并发会话或运行时长）

响应示例
{
  "error": "string",
  "message": "string"
}
响应 503

会话创建失败（没有可用健康运行节点）

响应示例
{
  "error": "string",
  "message": "string"
}

查询会话

GET/v1/sessions/{id}查看接口细节收起接口细节
GET/v1/sessions/{id}

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

路径参数

id必填字符串

会话 ID

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string", {  headers: {    "Authorization": "Bearer <token>"  }});
响应 200

会话详情

响应示例
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 404

资源不存在

响应示例
{
  "error": "string",
  "message": "string"
}

停止会话

POST/v1/sessions/{id}/stop查看接口细节收起接口细节
POST/v1/sessions/{id}/stop

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

路径参数

id必填字符串

会话 ID

cURL
curl -X POST "https://api.hivebrowser.ai/v1/sessions/string/stop" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/stop", {  headers: {    "Authorization": "Bearer <token>"  }});
响应 200

会话已停止

响应示例
{
  "data": {
    "id": "string",
    "teamId": "string",
    "status": "PENDING",
    "closeReason": "USER_REQUEST",
    "browserPlatform": "WINDOWS",
    "browserVersion": "string",
    "region": "string",
    "runnerId": "string",
    "profileId": "string",
    "endpoints": {
      "connectUrl": "http://example.com",
      "wsEndpoint": "http://example.com",
      "liveUrl": "http://example.com",
      "webdriverUrl": "http://example.com",
      "computerActionUrl": "http://example.com"
    },
    "proxy": {
      "server": "string",
      "username": "string",
      "password": "string",
      "bypass": [
        "string"
      ]
    },
    "viewport": {
      "width": 1,
      "height": 1,
      "deviceScaleFactor": 0
    },
    "timeoutSec": 0,
    "keepAlive": true,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "startedAt": "2019-08-24T14:15:22Z",
    "closedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 404

资源不存在

响应示例
{
  "error": "string",
  "message": "string"
}
响应 502

运行节点停止会话失败

响应示例
{
  "error": "string",
  "message": "string"
}

会话实时预览

GET/v1/sessions/{id}/live查看接口细节收起接口细节
GET/v1/sessions/{id}/live

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

路径参数

id必填字符串

会话 ID

查询参数

token字符串

用于免登录访问的实时预览令牌

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string/live?token=string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/live?token=string", {  headers: {    "Authorization": "Bearer <token>"  }});
响应 200

HTML 实时预览页面

响应示例
"string"
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 404

资源不存在

响应示例
{
  "error": "string",
  "message": "string"
}

会话实时截图

GET/v1/sessions/{id}/live/snapshot查看接口细节收起接口细节
GET/v1/sessions/{id}/live/snapshot

鉴权

Authorization必填Bearer <token>

在 Authorization 请求头中以 Bearer 令牌形式传入 API 密钥。

位置：header

x-hivebrowser-api-key<token>

也可以直接通过 x-hivebrowser-api-key 请求头传入 API 密钥。

位置：header

路径参数

id必填字符串

会话 ID

查询参数

token字符串

用于免登录访问的实时预览令牌

cURL
curl -X GET "https://api.hivebrowser.ai/v1/sessions/string/live/snapshot?token=string" \  -H "Authorization: Bearer <token>"
JavaScript
fetch("https://api.hivebrowser.ai/v1/sessions/string/live/snapshot?token=string", {  headers: {    "Authorization": "Bearer <token>"  }});
响应 200

截图图片

响应示例
"string"
响应 401

API 密钥缺失或无效

响应示例
{
  "error": "string",
  "message": "string"
}
响应 404

资源不存在

响应示例
{
  "error": "string",
  "message": "string"
}

本页目录

调用边界列出会话创建会话查询会话停止会话会话实时预览会话实时截图