Skip to main content
POST
当你希望立即获得一个正在运行的浏览器，而无需分步创建再启动时，使用此接口。单次 POST /cloud-browsers/launch 即可保存新配置并启动浏览器，阻塞等待浏览器进入 running 状态后才返回 201。响应中包含 runtime.connectUrl，在已登录配置所有者的浏览器中打开该 URL 即可进入交互式会话。停止浏览器后，已保存的配置会继续保留，可像手动创建的配置一样重启、查询或删除。
每次调用此接口都会创建新的配置，且没有幂等键。切勿自动重试失败的启动请求。如果响应中已包含 id，请先检查该配置并调用 POST /cloud-browsers/{id}/stop（带上重试）再尝试新的启动。
​
object
必填
自定义代理配置。无论使用何种认证方式，每次请求都必须提供。此处不允许用已保存的代理、托管地区或上次运行的代理替代。请提供 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，或同时提供两者且均为非空字符串。代理失败绝不会回退到直连。
​
array
浏览器启动时要打开的 HTTP(S) 标签页 URL。默认为 []（不注入标签页）。最多 8 个条目，每个 URL 最长 16,384 字节，不能包含嵌入的凭证、控制字符或首尾空白。每个条目可以是 URL 字符串或对象 { url, active? }。最多将其中一个标签页的 active 设为 true 以使其成为活动标签页；未指定时第一个标签页为活动标签页。
​
array
浏览器打开前要注入的 Cookie。默认为 []。在 1 MiB 请求限制内最多 10,000 条。每条必需字段：name、domain（均为非空字符串）；value 默认为空字符串。可选字段：path（默认为 /）、secure、httpOnly、session（均为布尔值）、expires（Unix 时间戳秒数）、sameSite（Strict | Lax | None）。过期条目会被过滤；未知字段和无效类型会被拒绝。
​
object
本次会话的浏览器指纹设置。默认值：webRtc=forward；其他所有信号（webGl、webGpu、webGlImage、canvas、audioContext、clientRects、speechVoices、fonts、hardware、doNotTrack）默认为 random。部分输入会自动填充剩余默认值。可选的 hardwareConcurrency 和 deviceMemory 接受 1 到 64 的整数；服务器会生成运行时种子。
​
string (UUID)
使用会话 cookie 或 Authorization: Bearer 认证时必需。选择你账户下用于计费的活跃 API 密钥。使用 x-api-key 直接认证时此字段可选，如果提供则必须与 Header 中的密钥一致。

​
响应

仅在浏览器达到 running 状态后返回。Location 响应 Header 指向 GET /cloud-browsers/{id}，用于后续查询。
​
boolean
成功时始终为 true。
​
string (UUID)
持久配置标识符。请立即保存，你需要用它来停止、查询或删除浏览器。
​
string
通过此接口创建的配置始终为 "launch"。
​
boolean
始终为 false。浏览器停止后配置继续保留。
​
object
响应发送时的运行时状态。

​
错误状态码

当响应包含 id 且状态码为 5xx 时，请不要自动重试启动。而应调用 POST /cloud-browsers/{id}/stop 并配合有限重试循环，直到 runtime.status 达到 stopped，然后再决定是否重新启动。