窗口 Local API 文档

打开窗口

标题

打开窗口

简要描述

根据窗口 ID 或窗口 UUID 打开一个浏览器窗口。

请求URL

http://127.0.0.1:54345/browser/open

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "Browser opened",
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "browserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "opened": true
  }
}

成功返回示例的参数说明

备注

单次只能打开一个窗口。接口只监听本机 127.0.0.1，调用前请先打开并登录客户端。

关闭窗口

标题

关闭窗口

简要描述

根据窗口 ID 或窗口 UUID 关闭一个浏览器窗口。

请求URL

http://127.0.0.1:54345/browser/close

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "Browser closed",
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "browserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "opened": false,
    "close": true
  }
}

成功返回示例的参数说明

备注

单次只能关闭一个窗口。接口只监听本机 127.0.0.1，调用前请先打开并登录客户端。

创建或编辑窗口

标题

创建或编辑窗口

简要描述

不传窗口标识时创建窗口，传窗口标识时编辑窗口。编辑窗口时必须传 config，可先通过 /browser/detail 获取当前窗口配置后原样带回。

创建窗口支持两种方式：

调用模式判定

如果请求 Body 中带了类似 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 的占位 UUID，本地 API 会按“编辑窗口”处理，并可能返回 {"code":211,"msg":"UUID 无效","data":{}}。

请求URL

http://127.0.0.1:54345/browser/update

请求方式

POST

Header

请求Body参数

最少字段创建请求示例

{
  "name": "Local API 最少字段窗口"
}

完整配置创建请求示例

{
  "name": "Local API 完整配置窗口",
  "group_id": 0,
  "config": {
    "browser_type": "firefox",
    "name": "Local API 完整配置窗口",
    "browser_name": "Local API 完整配置窗口",
    "group_id": 0,
    "proxy": {
      "type": "direct"
    },
    "fingerprint": {
      "noise_seed": "A1B2C3D4E5F60708",
      "canvas": { "mode": "on" },
      "audio_context": { "mode": "on" },
      "webgl_image": { "mode": "on" },
      "webgl_metadata": {
        "mode": "real",
        "vendor": "",
        "renderer": ""
      },
      "fonts": {
        "mode": "random",
        "font_list": [],
        "client_rects": true
      }
    },
    "navigator": {
      "user_agent": "",
      "cpu": { "mode": "custom", "value": 8 },
      "ram": { "mode": "custom", "value": 8 },
      "do_not_track": true
    },
    "webrtc": { "mode": "relay" },
    "geo": {
      "timezone": { "mode": "auto" },
      "geolocation": { "mode": "auto", "permission": "allow" },
      "language": { "mode": "auto", "values": [] }
    },
    "resolution": {
      "mode": "random",
      "width": 1920,
      "height": 1080
    },
    "cookies": { "mode": "merge", "items": [] },
    "launch_args": [],
    "extensions": [],
    "startup_pages": [],
    "raw": {
      "name": "Local API 完整配置窗口",
      "browser_name": "Local API 完整配置窗口",
      "group_id": 0,
      "proxy_method": "2",
      "proxy_type": "noproxy"
    }
  }
}

config 完整窗口配置字段说明

编辑窗口时，建议先调用 /browser/detail 获取当前窗口的 data.config，修改需要变更的字段后再原样传回。下面表格用于理解或手动构造完整 config 对象；不同客户端/服务端版本可能会额外返回扩展字段，未识别字段建议保留。

#### config 顶层字段

#### config.cache_storage 缓存存储配置

#### config.proxy 代理配置

#### config.fingerprint 指纹底层配置

#### config.navigator Navigator 与设备信息配置

#### config.webrtc、config.geo、config.resolution

#### config.cookies、config.credentials、config.syncConfig

#### 其他配置对象

#### config.raw 原始表单字段

raw 用于保存客户端表单原始字段，编辑窗口时建议保留。很多字段和 config 顶层、proxy、fingerprint 会互相映射。

#### raw.browserFingerPrint 表单层指纹字段

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 10001,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "测试窗口",
    "group_id": 0,
    "cache_storage_mode": "local"
  }
}

成功返回示例的参数说明

创建窗口请求示例

{
  "name": "测试窗口",
  "group_id": 0,
  "remark": "Local API 创建",
  "cache_storage_mode": "local",
  "proxy_method": "2",
  "proxy_type": "noproxy"
}

编辑窗口请求示例

编辑前先调用 /browser/list 获取真实 uuid，再调用 /browser/detail 获取 data.config，最后将完整 config 原样带回。

{
  "uuid": "真实窗口UUID",
  "name": "新窗口名",
  "remark": "Local API 编辑",
  "cache_storage_mode": "local",
  "config": {
    "...": "这里放 /browser/detail 返回的 data.config 完整对象"
  }
}

Postman 调用提示

导入根目录 LOCAL_API.postman_collection.json 后：

1. 创建窗口使用 Browser / Create Browser，不要在 Body 中添加 uuid 或 id。
2. 编辑窗口先运行 Browser / List Browsers 获取真实 browser_uuid。
3. 再运行 Browser / Get Browser Detail 保存 browser_config。
4. 最后运行 Browser / Update Existing Browser - Requires Real UUID And Detail Config。

备注

创建带代理窗口时需按代理类型传入 proxy_method、proxy_type、host、port 等字段。不使用代理时可传 {"proxy_method":"2","proxy_type":"noproxy"}。历史字段 proxyMethod / proxyType 仍兼容。

批量创建窗口

标题

批量创建窗口

简要描述

按数量或按窗口配置列表批量创建浏览器窗口。

批量创建同样支持两种方式：

请求URL

http://127.0.0.1:54345/browser/create/batch

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "list": [
      {
        "id": 10001,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1",
        "name": "Postman批量窗口-1"
      },
      {
        "id": 10002,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2",
        "name": "Postman批量窗口-2"
      }
    ]
  }
}

最少字段按数量批量创建请求示例

{
  "create_count": 2,
  "name_prefix": "Postman批量窗口-"
}

最少字段按列表批量创建请求示例

{
  "name_prefix": "Postman列表窗口-",
  "items": [
    {
      "name": "Postman列表窗口-1",
      "group_id": 0
    },
    {
      "name": "Postman列表窗口-2",
      "group_id": 0,
      "browserFingerPrint": {
        "webRTC": "3",
        "resolutionType": "2"
      }
    }
  ]
}

完整配置按列表批量创建请求示例

{
  "name_prefix": "Postman完整配置窗口-",
  "items": [
    {
      "name": "Postman完整配置窗口-1",
      "group_id": 0,
      "config": {
        "browser_type": "firefox",
        "name": "Postman完整配置窗口-1",
        "browser_name": "Postman完整配置窗口-1",
        "group_id": 0,
        "proxy": { "type": "direct" },
        "fingerprint": {
          "noise_seed": "A1B2C3D4E5F60708",
          "canvas": { "mode": "on" },
          "audio_context": { "mode": "on" },
          "webgl_image": { "mode": "on" },
          "webgl_metadata": {
            "mode": "real",
            "vendor": "",
            "renderer": ""
          },
          "fonts": {
            "mode": "random",
            "font_list": [],
            "client_rects": true
          }
        },
        "navigator": {
          "user_agent": "",
          "cpu": { "mode": "custom", "value": 8 },
          "ram": { "mode": "custom", "value": 8 }
        },
        "webrtc": { "mode": "relay" },
        "geo": {
          "timezone": { "mode": "auto" },
          "geolocation": { "mode": "auto", "permission": "allow" },
          "language": { "mode": "auto", "values": [] }
        },
        "resolution": { "mode": "random" },
        "cookies": { "mode": "merge", "items": [] },
        "raw": {
          "name": "Postman完整配置窗口-1",
          "browser_name": "Postman完整配置窗口-1",
          "group_id": 0,
          "proxy_method": "2",
          "proxy_type": "noproxy"
        }
      }
    }
  ]
}

常见错误

如果按 items 创建时返回 {"code":211,"msg":"name prefix required","data":{}}，请在请求 Body 外层补充 name_prefix，不要只在 items[].name 中填写窗口名。

成功返回示例的参数说明

备注

同等可用路径：/browser/batch-create、/browser/createBatch。如果要创建到指定分组并绑定标签，请先调用分组和标签列表接口获取真实 ID。不传 proxy_method / proxy_type 时，本地 API 默认按 proxy_method=2、proxy_type=noproxy 创建。create_count 适合所有窗口使用同一套顶层参数；如果每个窗口要设置不同完整字段，请使用 items[].config。

批量修改窗口配置

标题

批量修改窗口配置

简要描述

批量修改多个窗口的配置字段，也可同步修改分组、标签或备注。

请求URL

http://127.0.0.1:54345/browser/update/partial

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "updated": 2
  }
}

成功返回示例的参数说明

备注

示例配置：{"config":{"syncCookies":true,"browserFingerPrint":{"webRTC":"3"}},"configFields":["syncCookies","browserFingerPrint.webRTC"]}。如果只批量修改备注，可传 {"ids":[10001],"remark":"新备注"}。

查询窗口列表

标题

查询窗口列表

简要描述

分页查询窗口列表，支持按分组、名称、备注和状态筛选。

请求URL

http://127.0.0.1:54345/browser/list

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 10001,
        "backend_id": 10001,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "测试窗口",
        "group_id": 0,
        "remark": "Local API 创建",
        "cache_storage_mode": "local"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

成功返回示例的参数说明

备注

Local API 默认会向云端列表传 lite=1，轻量列表不会返回完整 config。编辑、复制、查看完整配置时请再调用 /browser/detail。返回字段可能随服务端版本增加。批量修改窗口分组、备注、代理时，优先使用列表返回的 backend_id / browserId 作为 ids。

查询窗口详情

标题

查询窗口详情

简要描述

根据窗口 UUID 或窗口 ID 查询窗口详情。

请求URL

http://127.0.0.1:54345/browser/detail

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 10001,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "测试窗口",
    "group_id": 0,
    "remark": "Local API 创建",
    "cache_storage_mode": "local",
    "config": {}
  }
}

成功返回示例的参数说明

备注

建议优先使用 uuid 查询详情；如果只传数字 ID，本地 API 会先通过列表解析到对应 UUID。

删除窗口

标题

删除窗口

简要描述

删除单个或多个窗口。

请求URL

http://127.0.0.1:54345/browser/delete

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001]
  }
}

成功返回示例的参数说明

备注

该接口会将窗口移入回收站/执行删除逻辑，具体行为以客户端和服务端当前配置为准。

批量删除窗口

标题

批量删除窗口

简要描述

根据窗口 ID 数组批量删除窗口。

请求URL

http://127.0.0.1:54345/browser/delete/ids

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002]
  }
}

成功返回示例的参数说明

备注

如果要删除单个窗口，也可以使用 /browser/delete。

批量修改窗口分组

标题

批量修改窗口分组

简要描述

将多个窗口移动到指定分组。

请求URL

http://127.0.0.1:54345/browser/group/update

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "group_id": 123
  }
}

成功返回示例的参数说明

备注

如果从 /browser/list 取窗口标识，优先使用返回里的 backend_id / browserId 作为 ids；如果只拿到 uuid / config_uuid，请传 uuids。

批量修改窗口备注

标题

批量修改窗口备注

简要描述

批量修改多个窗口的备注。

请求URL

http://127.0.0.1:54345/browser/remark/update

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "remark": "批量备注"
  }
}

成功返回示例的参数说明

备注

如果从 /browser/list 取窗口标识，优先使用返回里的 backend_id / browserId 作为 ids；如果只拿到 uuid / config_uuid，请传 uuids。

查询代理列表

标题

查询代理列表

简要描述

分页查询代理 IP 管理中的代理列表，支持按名称、代理方式、代理类型、归属用户、地区和检测状态筛选。

请求URL

http://127.0.0.1:54345/proxy/list

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "proxy_name": "测试代理",
        "proxy_method": "custom",
        "proxy_type": "http",
        "host": "127.0.0.1",
        "port": 7890,
        "username": "",
        "country": "CN",
        "region": "Shanghai",
        "check_status": 1
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

成功返回示例的参数说明

备注

该接口本地转发到后端 /api/browser/proxies/list。本地路径也兼容 /browser/proxy/list 和 /browser/proxies/list。返回字段可能随服务端版本增加。

批量修改窗口代理

标题

批量修改窗口代理

简要描述

批量修改多个窗口的代理配置。

请求URL

http://127.0.0.1:54345/browser/proxy/update

请求方式

POST

Header

请求Body参数

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "proxy_method": "2",
    "proxy_type": "noproxy"
  }
}

成功返回示例的参数说明

备注

如果从 /browser/list 取窗口标识，优先使用返回里的 backend_id / browserId 作为 ids；如果只拿到 uuid / config_uuid，请传 uuids。不使用代理时传：{"proxy_method":"2","proxy_type":"noproxy"}。