创建和管理持久化云浏览器会话

云浏览器为你提供持久化配置文件：存储的 cookies、一致的指纹和保存的代理偏好设置。你无需每次都重新从头配置，即可反复启动。每次启动都会从你离开的位置继续：浏览器打开时，你注入的 cookies 已设置，指纹已应用。

启动云浏览器

快速启动
先创建再启动

POST /cloud-browsers/launch 创建配置文件并等待浏览器运行后才返回。当你想要一个单一请求就能提供即用型 connectUrl 时，请使用此方式。

curl --fail-with-body -sS --max-time 200 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/launch' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "proxy": {
      "server": "http://proxy.example.com:8080",
      "username": "user",
      "password": "pass"
    },
    "tabs": ["https://example.com"],
    "cookies": [{
      "name": "session",
      "value": "abc123",
      "domain": "example.com",
      "path": "/"
    }]
  }'

成功的 201 响应包含一个可直接打开的 connectUrl：

{
  "ok": true,
  "id": "<browser-id>",
  "source": "launch",
  "deleteOnStop": false,
  "runtime": {
    "runtimeKind": "neko",
    "status": "running",
    "sessionId": "<session-id>",
    "expiresAt": "2026-09-07T09:00:00.000Z",
    "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
  }
}

每次调用 /cloud-browsers/launch 都会创建一个新的配置文件。如果请求失败或响应丢失，请在重试前检查 GET /cloud-browsers —— 切勿自动重复启动 POST。

当你想要更多控制时使用两个独立的请求 —— 例如，现在保存配置文件并在以后启动，或在消耗运行槽之前验证配置文件已创建。步骤 1 — 创建并保存配置文件：

curl --fail-with-body -sS \
  -X POST 'https://api.adscrawl.net/cloud-browsers' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "remark": "work profile",
    "browserSettings": {
      "viewport": { "width": 1440, "height": 900 }
    }
  }'

响应：{ "ok": true, "id": "<browser-id>" }步骤 2 — 启动配置文件（始终再次发送代理）：

curl --fail-with-body -sS --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "proxy": {
      "server": "http://proxy.example.com:8080",
      "username": "user",
      "password": "pass"
    }
  }'

每个 API 密钥启动请求都必须包含显式的 proxy 对象，即使配置文件已保存代理。保存的 browserSettings.proxy 不能替代它。

打开交互式浏览器查看器

一旦 runtime.status 为 "running"，在任何已登录 AdsCrawl 账户的浏览器中打开 connectUrl。查看器让你实时交互式地控制远程浏览器。

关闭查看器标签页不会停止云浏览器。 会话继续运行并按每分钟启动计费一积分。完成后务必调用 POST /cloud-browsers/:id/stop。

停止云浏览器

发送 POST 以停止运行中的会话：

curl --fail-with-body -sS --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/stop' \
  -H 'x-api-key: YOUR_API_KEY'

响应状态告诉你停止是否已确认：

HTTP 状态	`runtime.status`	含义
`200`	`stopped`	会话已完全停止；运行槽已释放
`202`	`stopping`	关闭进行中；配额仍被保留
`409`	—	启动仍在进行中；等待并重试

当你收到 202 时，轮询配置文件详情端点直到 stopped 被确认：

# 轮询直到停止（示例 — 在生产环境中添加上限）
until [ "$(curl -sS 'https://api.adscrawl.net/cloud-browsers/<browser-id>' \
  -H 'x-api-key: YOUR_API_KEY' | jq -r '.runtime.status')" = "stopped" ]; do
  echo "Still stopping..."
  sleep 2
done
echo "Stopped."

检查并发限制

检索你的当前配额使用情况以及配置文件列表：

curl -sS 'https://api.adscrawl.net/cloud-browsers?page=1&pageSize=10' \
  -H 'x-api-key: YOUR_API_KEY' | jq '{limit, runningLimit, runningCount}'

字段	含义
`limit`	你的套餐允许保存的最大配置文件数
`runningLimit`	你的账户允许的最大同时运行会话数
`runningCount`	当前处于 `starting`、`running` 或 `stopping` 状态的会话数

如果你超过 runningLimit，启动或启动请求将返回 409 CLOUD_BROWSER_CONCURRENCY_LIMIT。停止一个活动会话以释放槽位后再重试。这与 409 Cloud Browser limit reached 不同，后者表示你的保存配置文件配额已满。

配置文件保留与复用

deleteOnStop 默认为 false，因此你的配置文件 —— 包括保存的 cookies 和标签页快照 —— 在每次停止后都会保留。你可以根据需要多次重新启动同一配置文件，或在停止状态下查询它，而不会丢失累积的会话状态。

配置文件仅在你显式调用 DELETE /cloud-browsers/:id 时才会被移除。已停止的配置文件仍计入你的保存配置文件 limit，但不消耗任何运行槽。

运行时状态参考

运行时状态生命周期

status

浏览器正在初始化。运行槽已被保留。请勿在此配置文件上尝试再次启动；等待 running 或处理错误。

status

浏览器正在运行。connectUrl 存在于运行时对象中。计费已激活。

status

已请求停止但尚未确认。运行槽仍被保留。轮询直到 stopped。

status

会话已结束。运行槽已释放。保存的配置文件及其 cookies 被保留。

快速上手

核心概念

使用指南

价格与限制

创建和管理持久化云浏览器会话

启动云浏览器

打开交互式浏览器查看器

停止云浏览器

检查并发限制

配置文件保留与复用

运行时状态参考

​启动云浏览器

​打开交互式浏览器查看器

​停止云浏览器

​检查并发限制

​配置文件保留与复用

​运行时状态参考

启动云浏览器

打开交互式浏览器查看器

停止云浏览器

检查并发限制

配置文件保留与复用

运行时状态参考