启动云浏览器

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

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'Authorization: Bearer <SESSION_JWT>' \
  -H 'content-type: application/json' \
  --data '{
  "apiKeyId": "<api-key-id>",
  "countryCode": "GLOBAL"
}'

{
  "ok": true,
  "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"
  }
}

{
  "error": "API key starts require an explicit proxy in every request",
  "code": "PROXY_REQUIRED"
}

{
  "error": "Cloud browser running limit reached",
  "code": "CLOUD_BROWSER_CONCURRENCY_LIMIT"
}

{
  "error": "Cloud browser cluster has no available capacity",
  "code": "CLUSTER_NO_CAPACITY",
  "nextAvailableAt": null,
  "retryAfterMs": null
}

POST

cloud-browsers

{id}

start

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

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'Authorization: Bearer <SESSION_JWT>' \
  -H 'content-type: application/json' \
  --data '{
  "apiKeyId": "<api-key-id>",
  "countryCode": "GLOBAL"
}'

{
  "ok": true,
  "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"
  }
}

{
  "error": "API key starts require an explicit proxy in every request",
  "code": "PROXY_REQUIRED"
}

{
  "error": "Cloud browser running limit reached",
  "code": "CLOUD_BROWSER_CONCURRENCY_LIMIT"
}

{
  "error": "Cloud browser cluster has no available capacity",
  "code": "CLUSTER_NO_CAPACITY",
  "nextAvailableAt": null,
  "retryAfterMs": null
}

通过配置的 id 启动已保存的云浏览器配置。此接口会阻塞直到浏览器进入 running 状态，然后返回 200 及完整的运行时对象（包括 connectUrl），以便你立即打开交互式会话。成功的 200 响应意味着 计费已开始：从此时起直到你调用 POST /cloud-browsers/{id}/stop，每分钟启动时间消耗 1 积分。

string (UUID)

必填

由 POST /cloud-browsers（创建）或 GET /cloud-browsers（列表）返回的持久配置标识符。此值与运行时 sessionId 不同。

object

必填

每次使用 x-api-key 启动时必需。即使在配置的 browserSettings 中已保存代理，每次启动请求也必须提供有效的顶层 proxy。已保存的代理、托管 countryCode 或上次运行的代理均不能满足此要求。请提供 server 形式或拆分的 protocol + host + port 形式：

server — 完整 URL：http://proxy.example.com:8080 或 socks5://proxy.example.com:1080。必须包含显式端口（1–65535）。不能包含嵌入的凭证、路径、查询参数或片段。不能与 host 同时使用。
protocol — http 或 socks5。
host — 代理主机名。
port — 整数或数字字符串，范围 1 到 65535。

无需认证时省略 username 和 password，或同时提供两者且均为非空字符串。代理失败绝不能回退到直连。启动覆盖仅影响本次运行，不会更新已保存的配置。

string (UUID)

使用会话 cookie 或 Authorization: Bearer 认证时必需。选择属于你账户的活跃、未过期 API 密钥。使用 x-api-key 认证时当前密钥会自动选中，如果同时提供了 apiKeyId，则必须与当前密钥一致。

string

仅对会话 / Bearer 调用者可用，不接受 x-api-key。使用 GLOBAL 表示随机热门地区，或使用两位 ISO 代码如 FR 以优先选择该地区的可信代理并启用动态回退。空字符串不是有效选项。不能与同一请求中的 proxy 同时使用。此覆盖仅影响本次运行，不会更新已保存的配置。

array

可选的每次运行 Cookie 覆盖。仅对本次运行优先于配置中保存的所有 Cookie，不会更新已保存的配置。

object

可选的每次运行指纹覆盖，按字段与已保存的设置合并，仅影响本次运行。支持的字段：webRtc（forward | real | disabled）、webGl / webGlImage / canvas / audioContext / clientRects / speechVoices / fonts / hardware（均为 random | real）、webGpu（random | real | disabled）、doNotTrack（random | enabled | disabled）。旧版 hardwareConcurrency 和 deviceMemory 接受整数 1–64。无效或冲突的组合会返回 INVALID_FINGERPRINT_SETTINGS。

响应

boolean

成功时始终为 true。

object

确认时的运行时状态。

显示 Runtime 字段

string

neko 或 worker_cdp。neko 省略 cdpBaseUrl。

string

成功的 200 响应中始终为 "running"。

string

活跃会话标识符。

string (RFC3339)

会话过期时间戳。

string

交互式浏览器查看器的直接 URL。在已登录配置所有者的浏览器中打开。请按原样使用返回的 URL。

计费从成功的 200 响应开始，直到你通过 POST /cloud-browsers/{id}/stop 确认停止，按 每分钟启动时间 1 积分 计算。关闭查看器标签页或失去连接不会停止计费。

状态码	含义
200	浏览器已进入运行状态。计费从此响应开始。
400	`PROXY_REQUIRED`（API 密钥启动缺少顶层代理）、`INVALID_PROXY`、`COUNTRY_PROXY_CONFLICT`（同时提供了 `proxy` 和 `countryCode`）、`INVALID_COUNTRY_CODE`、`INVALID_FINGERPRINT_SETTINGS`，或 Cookie 无效。使用会话 / Bearer 认证时 `apiKeyId` 缺失或无效也会返回 `400`。
401	认证缺失、无效或已过期。
402	`PAID_PLAN_REQUIRED`（没有活跃的付费套餐）或 `INSUFFICIENT_CREDITS`（可用积分少于 1 分）。响应包含 `balance` 和 `requiredCredits` 字段。
403	提供的 `apiKeyId` 属于其他用户，或与认证密钥不匹配。
404	配置不存在或属于其他用户。
409	`CLOUD_BROWSER_CONCURRENCY_LIMIT`：你的运行配额已满或设为 `0`。停止另一个浏览器释放槽位后再重试。响应包含 `runningLimit` 和 `runningCount`。或浏览器已在运行（无错误码）：此配置已存在处于 `starting`、`running` 或 `stopping` 状态的活跃会话。请先停止它，等待变为 `stopped`，然后再次启动。
502	`CLOUD_RUNTIME_AUTH_FAILED`、`CLOUD_RUNTIME_NOT_FOUND`、`CLOUD_RUNTIME_HTTP_ERROR`、`CLOUD_RUNTIME_INVALID_RESPONSE` 或 `CLOUD_RUNTIME_CONTROLLER_FAILED`。
503	`CLUSTER_NO_CAPACITY`（包含可空的 `nextAvailableAt` 和 `retryAfterMs`）、`CDP session capacity exhausted`、`MANAGED_PROXY_UNAVAILABLE`、`DYNAMIC_PROXY_NOT_CONFIGURED`、`CLOUD_RUNTIME_UNREACHABLE` 或 `CLOUD_RUNTIME_CONFIG_INVALID`。代理失败绝不会回退到直连，请在重试前修复代理。
504	`CLOUD_RUNTIME_TIMEOUT`。超时不能证明运行时不存在。请检查配置状态并在需要时调用停止；运行槽位会保留直到清理确认完成。
500	内部服务故障。

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

curl --fail-with-body --silent --show-error --max-time 65 \
  -X POST 'https://api.adscrawl.net/cloud-browsers/<browser-id>/start' \
  -H 'Authorization: Bearer <SESSION_JWT>' \
  -H 'content-type: application/json' \
  --data '{
  "apiKeyId": "<api-key-id>",
  "countryCode": "GLOBAL"
}'

{
  "ok": true,
  "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"
  }
}

{
  "error": "API key starts require an explicit proxy in every request",
  "code": "PROXY_REQUIRED"
}

{
  "error": "Cloud browser running limit reached",
  "code": "CLOUD_BROWSER_CONCURRENCY_LIMIT"
}

{
  "error": "Cloud browser cluster has no available capacity",
  "code": "CLUSTER_NO_CAPACITY",
  "nextAvailableAt": null,
  "retryAfterMs": null
}

概览

浏览器任务

远程 CDP

云浏览器

启动云浏览器

响应

​响应

响应