创建环境

客户端版本版本概览

POST

/api/v1/browsers

创建当前用户、当前团队下的单个未启动环境。请求只包含公开配置意图；Local API 注入真实桌面平台并在本机解析 API 代理，后端负责生成 UA Client Hints、噪声、电池和媒体设备等内部指纹值。

请求参数

Authorization Bearer Token

在请求头 Authorization 中使用 Bearer Token 传入 API Key。

Authorization: Bearer <api-key>

Body 参数

必填application/jsonBrowserCreateRequest

字段说明

string必填

环境名称

minLength: 1maxLength: 32

object

浏览器窗口尺寸；不传时使用 800 x 600

默认值{"width":800,"height":600}

不允许额外字段。

object必填

浏览器内核、指纹系统和 User-Agent 兼容条件

不允许额外字段。

string | null

环境分组 ID；不传或传 null 时使用默认分组

minLength: 1maxLength: 32

object[] | null

Puppeteer Cookie 对象列表；每项至少包含 name 和 value

maxItems: 500

string | null

环境备注

maxLength: 5000

string | null

浏览器启动参数，格式与图形界面环境配置一致

maxLength: 5000

object

环境代理设置；不传时不使用代理

默认值{"mode":"none"}

string[]

绑定账号管理中已有账号的 ID 列表

默认值[]

maxItems: 100

每项元素：

账号唯一标识

示例值"account_01JABCDEF1234567890"

minLength: 1

object[]

随环境创建并绑定的账号；使用该字段还需要当前用户具备账号创建权限

默认值[]

maxItems: 20

string[]

需要绑定的个人或团队扩展 ID 列表

默认值[]

maxItems: 100

每项元素：

扩展唯一标识

示例值"extension_01JABCDEF1234567890"

minLength: 1

object

浏览器常用设置；对象和未传的子字段均使用各字段默认值

默认值

{"image_size_limit_kb":null,"restore_last_session":true,"block_video_autoplay":false,"disable_video_preload":false,"mute_audio":false,"disable_translate_prompt":false,"disable_password_save_prompt":false,"block_notifications":false,"block_clipboard_read":false,"stop_open_on_network_error":false,"stop_open_on_ip_change":false,"stop_open_on_country_change":false,"search_engine_preset":null}

不允许额外字段。

object

浏览器指纹配置；不传时使用各字段的默认模式

默认值

{"webrtc":{"mode":"based_on_ip"},"timezone":{"mode":"based_on_ip"},"geolocation":{"mode":"based_on_ip"},"language":{"mode":"based_on_ip"},"screen":{"mode":"random"},"fonts":{"mode":"random"},"noise":{"canvas":true,"webgl":true,"audio_context":true,"client_rects":true},"memory":{"mode":"random"},"cpu":{"mode":"random"},"do_not_track":{"mode":"default"},"port_scan_protection":{"mode":"enabled"},"hardware_acceleration":{"mode":"default"},"battery":{"mode":"random"},"media_devices":{"mode":"random"}}

不允许额外字段。

boolean

每次打开环境时是否重新随机指纹

默认值false

根据数据模型生成，非实际请求结果。

{
  "name": "string",
  "browser": {
    "kernel_version": "string"
  }
}

请求示例代码

JavaScript / TypeScript 使用 Node.js 18+ 内置 fetch；PHP 需启用 cURL 扩展；Go 需 1.16+；Java 需 JDK 11+。运行前请替换 Token 和示例参数值。

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' -d '{
  "name": "string",
  "browser": {
    "kernel_version": "string"
  }
}' 'http://local.zhongyibrowser.com:39025/api/v1/browsers'

fetch("http://local.zhongyibrowser.com:39025/api/v1/browsers", {
  method: "POST",
  headers: {
      "Authorization": "Bearer <TOKEN>",
      "Content-Type": "application/json"
    },
  body: "{\n  \"name\": \"string\",\n  \"browser\": {\n    \"kernel_version\": \"string\"\n  }\n}",
})
  .then((response) => response.json())
  .then((data) => console.log(data))

async function main(): Promise<void> {
  const options: RequestInit = {
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <TOKEN>",
      "Content-Type": "application/json"
    },
    "body": "{\n  \"name\": \"string\",\n  \"browser\": {\n    \"kernel_version\": \"string\"\n  }\n}"
  }
  const response: Response = await fetch("http://local.zhongyibrowser.com:39025/api/v1/browsers", options)
  const data: unknown = await response.json()
  console.log(data)
}

main().catch(console.error)

<?php
$ch = curl_init('http://local.zhongyibrowser.com:39025/api/v1/browsers');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "name": "string",
  "browser": {
    "kernel_version": "string"
  }
}',
]);

$response = curl_exec($ch);
if ($response === false) {
  throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
echo $response . PHP_EOL;

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "http://local.zhongyibrowser.com:39025/api/v1/browsers", strings.NewReader(`{
  "name": "string",
  "browser": {
    "kernel_version": "string"
  }
}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer <TOKEN>")
	req.Header.Set("Content-Type", "application/json")

	response, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()

	data, err := io.ReadAll(response.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String body = "{\n" +
        "  \"name\": \"string\",\n" +
        "  \"browser\": {\n" +
        "    \"kernel_version\": \"string\"\n" +
        "  }\n" +
        "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("http://local.zhongyibrowser.com:39025/api/v1/browsers"))
        .header("Authorization", "Bearer <TOKEN>")
        .header("Content-Type", "application/json")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

import requests

url = "http://local.zhongyibrowser.com:39025/api/v1/browsers"
headers = {
    "Authorization": "Bearer <TOKEN>",
    "Content-Type": "application/json"
}
data = "{\n  \"name\": \"string\",\n  \"browser\": {\n    \"kernel_version\": \"string\"\n  }\n}"

response = requests.post(url, headers=headers, data=data)
print(response.json())

返回响应

成功时 code = 0，失败时 code > 0。选择状态码查看对应字段和示例，展开对象可查看嵌套字段；可选字段可能不返回。

创建后的环境标识

Body

application/jsonBrowserCreateSuccessResponse

字段说明

number必填

业务状态码；成功固定为 0

枚举值

string必填

业务状态信息；成功固定为 success

枚举值

object必填

接口业务数据

不允许额外字段。

根据数据模型生成，非实际请求结果。

{
  "code": 0,
  "message": "success",
  "data": {
    "env_id": "env_01JABCDEF1234567890",
    "name": "string",
    "status": "inactive"
  }
}

查看全部业务错误码与 HTTP 状态码

创建环境 ​

请求参数

请求示例代码

返回响应

创建环境