Container API 接口文档

简介

Container API 提供了容器和主机管理的一系列能力，涵盖了主机信息查询、镜像管理、系统控制、实例生命周期管理等功能。

调用方式

1. HTTP 调用

从宿主机或网络中的其他设备调用：

URL 格式: http://{主机IP}:18182/{接口路径}
示例: http://192.168.1.100:18182/v1/get_hardware_cfg

安全提示

当前接口面向可信局域网使用。请勿将 18182 端口直接暴露到公网；Shell、备份、网络配置、整盘迁移和远程调试接口均具有高权限。调用方还应同时检查 HTTP 状态和响应中的业务字段 code，其中 200 表示成功。

2. MCP 调用（AI Agent 集成）

通过 MCP（Model Context Protocol）将容器与主机管理能力直接暴露给 AI Agent，支持 Claude Code、Cursor、Codex、Gemini、通义千问、Kimi 等任意兼容 MCP SSE 协议的客户端。

SSE 端点：http://{主机IP}:18182/mcp/sse

bash

# 项目级（仅当前项目生效，默认）
claude mcp add --transport sse vmos-edge-container-api http://{主机IP}:18182/mcp/sse
# 全局（所有项目生效）
claude mcp add -s user --transport sse vmos-edge-container-api http://{主机IP}:18182/mcp/sse

# 移除
claude mcp remove vmos-edge-container-api
# 禁用（保留配置但不加载）
claude mcp disable vmos-edge-container-api
# 启用
claude mcp enable vmos-edge-container-api
# 查看列表
claude mcp list

yaml

# ~/.codex/config.yaml
mcp_servers:
  vmos-edge-container-api:
    type: sse
    url: "http://{主机IP}:18182/mcp/sse"

json

// ~/.gemini/settings.json
{
  "mcpServers": {
    "vmos-edge-container-api": {
      "httpUrl": "http://{主机IP}:18182/mcp/sse"
    }
  }
}

json

// 项目根目录 .cursor/mcp.json 或 ~/.cursor/mcp.json
{
  "mcpServers": {
    "vmos-edge-container-api": {
      "url": "http://{主机IP}:18182/mcp/sse"
    }
  }
}

json

// 在"MCP 服务"配置中添加
{
  "mcpServers": {
    "vmos-edge-container-api": {
      "type": "sse",
      "url": "http://{主机IP}:18182/mcp/sse"
    }
  }
}

连接成功后，AI 可直接调用主机信息、镜像管理、实例生命周期等工具，无需手动构造 HTTP 请求。

3. Skills 调用（AI Agent 集成）

推荐优先使用官方 skills 仓库 vmos-dev/vmos-edge-skills。

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-container-api

通用响应结构

所有接口均返回标准 JSON 格式，统一响应结构如下：

json

{
    "code": 200,            // 状态码，200 为成功
    "data": { ... },        // 具体的业务数据
    "msg": "OK"             // 状态描述
}

主机管理 (Host)

获取主机配置信息

返回设备硬件与基础运行信息。

URL: /v1/get_hardware_cfg
方式: GET

返回示例:

json

{
  "code": 200,
  "message": "success",
  "data": {
    "cpuload": "0%",
    "cputemp": 33,
    "device_id": "93508a1ed52c4e1dee17320ec78f806a",
    "hwaddr": "82:C1:32:C6:E4:34",
    "ip": "192.168.10.20",
    "mem_total": "15943",
    "mem_use": "689",
    "mmc_total": "239281",
    "mmc_use": "20691",
    "ssd_total": "",
    "ssd_use": "",
    "model": "c1_10",
    "version": "QL-c1-2025.v0.3.0.202503311512"
  }
}

获取主机系统信息

返回 CPU 使用率、磁盘/内存占用、温度、swap 等指标。

URL: /v1/systeminfo
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": {
    "cpu": 5.4,
    "disk_percent": 39.3,
    "disk_total": 250903556096,
    "mem_percent": 63.9,
    "mem_total": 16720510976,
    "temperatures": 29.615,
    "swap_total": 0,
    "swap_percent": 0
  }
}

获取主机网络配置

返回主机当前网关、子网掩码和子网段。

URL: /v1/net_info
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "gateway": "192.168.10.1",
    "netmask": "255.255.254.0",
    "subnet": "192.168.10.0/23"
  }
}

主机心跳检查

检查主机 HTTP/Docker/Ping 可用性。

URL: /v1/heartbeat
方式: GET

返回示例:

json

{
  "code": 200,
  "message": "主机正常",
  "data": {
    "docker_status": true,
    "http_status": true,
    "ping_status": true
  }
}

获取主机镜像列表

返回 docker images 列表的 repository 与 image_id。

URL: /v1/get_img_list
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "repository": "armcloud/demo:latest",
      "image_id": "sha256:..."
    }
  ]
}

清理未使用镜像

清理主机上未使用的 Docker 镜像。

URL: /v1/prune_images
方式: GET
返回值说明:
code 说明
200 成功
201 失败
1 主机不通

code	说明
200	成功
201	失败
1	主机不通

返回示例:

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "freed_mb": "542.15",
    "images": [
      "vcloud_android13_edge_20250925011125",
      "vcloud_android12_edge_20250920010230"
    ]
  }
}

导入镜像

上传镜像文件到主机并加载镜像。

URL: /v1/import_image
方式: POST
Content-Type: multipart/form-data
参数:
参数名类型必选说明
file file 是镜像文件（.tar.gz 或 .tar 格式）
流式返回进度（NDJSON 格式）:
- 阶段说明:
  1. Uploading: 上传中（upload_progress=100%, load_progress=0%）
  2. Loading: 加载中（upload_progress=100%, load_progress=1-99%）
  3. Success: 成功（upload_progress=100%, load_progress=100%）
  4. Failed: 失败（upload_progress=100%, load_progress=0%）
返回值说明:
code 说明
200 成功（流式返回）
0 失败（文件格式错误、上传失败、加载失败等）

参数名	类型	必选	说明
file	file	是	镜像文件（.tar.gz 或 .tar 格式）

code	说明
200	成功（流式返回）
0	失败（文件格式错误、上传失败、加载失败等）

设置Swap开关

设置主机 swap 分区的状态：1 为开启，0 为关闭。默认为关闭状态；插入 SSD 后支持开启；swap 分区默认大小为 8G（位于 /container_nswc_lv/.swapfile）。

URL: /v1/swap/{enable}
方式: GET
参数:
参数名类型必选说明
enable string 是 1=开启 0=关闭

参数名	类型	必选	说明
enable	string	是	1=开启 0=关闭

返回示例:

json

{
  "code": 200,
  "msg": {
    "swap_total": 2147483648,
    "swap_percent": 0
  }
}

重启主机

下发后异步重启主机。

URL: /v1/reboot_for_arm
方式: GET
返回示例:
json
```
{
  "code": 200,
  "msg": "rebooting"
}
```

主机关机

下发后异步关闭主机。执行 shutdown -h now 命令。

URL: /v1/shutdown
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": "正在关机",
  "data": {
    "host_ip": "192.168.1.100"
  }
}

重置主机

销毁容器、清理映射、格式化并挂载数据盘、清理根分区后重启。

URL: /v1/reset
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": "resetting and rebooting"
}

发现服务状态

返回 UDP 应答器状态。

URL: /v1/discover
方式: GET

返回示例:

json

{
  "code": 200,
  "msg": "UDP发现服务状态",
  "data": {
    "udp_responder": {
      "running": true
    }
  }
}

导入机型模板

导入机型模板到主机。

URL: /v1/import_adi
方式: POST
Content-Type: multipart/form-data
参数:
参数名类型必选说明
adiZip file 是 ADI 模板文件（必须是 .zip 格式）
返回值说明:
字段说明
code 200 成功；0/1 失败
msg 操作结果说明
data.host_ip 主机 IP
data.filename 保存的文件名

参数名	类型	必选	说明
adiZip	file	是	ADI 模板文件（必须是 .zip 格式）

字段	说明
code	200 成功；0/1 失败
msg	操作结果说明
data.host_ip	主机 IP
data.filename	保存的文件名

返回示例:

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "filename": "template.zip"
  }
}

获取主机机型模板列表

列出主机上所有已上传且存在于 template.json 中的机型模板，支持按品牌和 AOSP 版本过滤，不带参数调用查询全部模板。只返回实际存在的文件。

URL: /v1/get_adi_list
方式: GET
参数:
参数名类型必选说明
brand string 否过滤品牌（如：vivo、google、samsung）
aosp_version string 否过滤AOSP版本（如：13、14）

参数名	类型	必选	说明
brand	string	否	过滤品牌（如：vivo、google、samsung）
aosp_version	string	否	过滤AOSP版本（如：13、14）

返回值说明:

字段	说明
code	200 成功；0 失败
msg	操作结果说明
data.host_ip	主机 IP
data.list	机型模板列表（对象数组，只返回实际存在的文件）
data.list[].adiID	模板ID
data.list[].brand	品牌
data.list[].model	型号
data.list[].model_name	型号名称
data.list[].aosp_version	AOSP版本
data.list[].layout	布局（宽度x高度xDPI）
data.list[].adiName	模板文件名（ZIP文件名）
data.list[].adiPass	模板解压密码

返回示例:

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "host_ip": "192.168.10.20",
    "list": [
      {
        "adiID": 2001,
        "brand": "google",
        "model": "Pixel 7 Pro(12G)",
        "model_name": "Pixel 7 Pro",
        "aosp_version": "13",
        "layout": "1440x3120x560",
        "adiName": "59ddfc6374723e2bea36a84792238063.zip",
        "adiPass": ""
      }
    ]
  }
}

实例管理 (Instance)

创建实例

创建安卓实例（bridge 网络、沙盒存储、动态端口分配）。

URL: /container_api/v1/create
方式: POST

参数:

参数名	类型	必选	说明
user_name	string	是	实例用户名，长度大于2，支持数字/字母/下划线/点/横线
count	integer	否	批量创建数量，默认 1，最大 12
bool_start	boolean	否	是否立即启动实例，默认 false
bool_macvlan	boolean	否	是否启用 macvlan 双网卡模式（bridge+macvlan），默认 false。启用后实例将获得独立的局域网 IP
bool_ping_disabled	boolean	否	macvlan 模式下是否禁用实例响应 Ping
macvlan_network	string	否	macvlan 网络名称，默认 macvlan100。仅在 bool_macvlan=true 时有效
macvlan_start_ip	string	否	macvlan 起始 IP 地址，仅在 bool_macvlan=true 时有效。count=1 时直接使用指定 IP（需 ARP 检测），count>1 时从起始 IP 开始递增分配
image_repository	string	否	本地镜像名称（不含tag），默认值为vcloud_android13_edge_20250925011125
bool_gms_disabled	boolean	否	是否在创建容器时禁用GMS，true=禁用，false=不禁用，不传则使用game.info里的值
bool_gms_upgrade_enable	boolean	否	是否允许GMS升级，true=允许，false=不允许，默认false
resolution	object	否	分辨率配置对象，包含 dpi、fps、height、width
scdArgs	string	否	SCD 推流配置的 JSON 字符串，例如 `{"video_bit_rate":"2097152","max_fps":"30"}`
selinux	boolean	否	是否启用 SELinux
dns	`array<string>`	否	DNS 服务器列表
adiID	integer	否	ADI 模板ID（优先级最高，通过 /v1/get_adi_list 获取可用模板ID），系统会自动查找对应的模板文件和密码
adiName	string	否	ADI 模板文件名（如果传了adiID，可以不用传adiName和adiPass）
adiPass	string	否	ADI 解压密码（如果传了adiID，可以不用传adiName和adiPass）
lon	float	否	经度。例如 121.5
lat	float	否	纬度。例如 31.2
locale	string	否	语言。例如 zh-CN
timezone	string	否	时区。例如 Asia/Shanghai
country	string	否	随机生成安卓属性使用的国家代码（ISO Alpha-2）。未填写时默认 CN
userProp	string	否	自定义安卓属性（JSON 格式字符串）
proxy	object	否	创建后立即应用的代理配置，字段与代理设置接口一致
cert_hash	string	否	证书文件哈希值（优先使用）。必须已通过证书管理接口导入到系统
cert_content	string	否	证书内容的 base64 编码（当未提供 cert_hash 时使用）。仅本次创建使用，不落库不落盘。注意：使用 cert_content 时，bool_start 必须为 true
device_type	string	否	设备类型。`virtual` 表示虚拟机，`real` 表示真机。默认为 `real`。注意：当 device_type 为 `virtual` 时，系统会强制置空 adiID、adiName、adiPass 三个参数
remark	string	否	实例备注信息

请求示例:

json

{
  "user_name": "test-001",
  "bool_start": false,
  "image_repository": "vcloud_android13_edge_20250925011125",
  "adiID": 1039,
  "resolution": {
    "dpi": 560,
    "fps": 60,
    "height": 3040,
    "width": 1440
  },
  "selinux": false,
  "dns": ["8.8.8.8", "1.1.1.1"],
  "bool_gms_disabled": false,
  "bool_gms_upgrade_enable": false
}

批量启动实例（异步）

批量启动实例（异步）。

URL: /container_api/v1/run
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID数组
scdArgs string 否 SCD 推流配置 JSON 字符串
返回值说明:
code 说明
200 成功，任务已入队
460 存在其他启动任务进行中
203 运行实例数量即将超限
1 db_id 不存在
2 实例不在 stopped 状态

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID数组
scdArgs	string	否	SCD 推流配置 JSON 字符串

code	说明
200	成功，任务已入队
460	存在其他启动任务进行中
203	运行实例数量即将超限
1	db_id 不存在
2	实例不在 stopped 状态

批量停止实例（异步）

批量停止实例（异步）。

URL: /container_api/v1/stop
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID数组

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID数组

批量重启实例（异步）

批量重启实例（异步）。

URL: /container_api/v1/reboot
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID数组
scdArgs string 否 SCD 推流配置 JSON 字符串

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID数组
scdArgs	string	否	SCD 推流配置 JSON 字符串

批量重置实例（异步）

批量重置实例（异步）。

URL: /container_api/v1/reset
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID数组
scdArgs string 否 SCD 推流配置 JSON 字符串

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID数组
scdArgs	string	否	SCD 推流配置 JSON 字符串

批量删除实例（异步）

批量删除实例（异步）。

URL: /container_api/v1/delete
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID数组

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID数组

升级实例镜像

将指定实例升级到新镜像版本。升级流程：停止容器 → 删除容器 → 使用新镜像重建 → 启动容器。数据会保留。

URL: /container_api/v1/upgrade_image
方式: POST

参数:

参数名	类型	必选	说明
db_ids	`array<string>`	是	db_id 数组
repository	string	是	镜像仓库名（不含tag，默认使用latest）
adiID	integer	否	ADI 模板ID（优先级最高）
adiName	string	否	ADI 模板文件名
adiPass	string	否	ADI 解压密码
scdArgs	string	否	重建后使用的 SCD 推流配置 JSON 字符串

重命名实例

仅修改 user_name，不修改 db_id/Name（容器名）。

URL: /container_api/v1/rename/{db_id}/{new_user_name}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识
new_user_name string 是新的 user_name（展示名称，长度大于2）

更新证书配置

更新指定实例的证书配置。优先使用 cert_hash（必须已通过证书管理接口导入到系统），如果未提供则使用 cert_content（base64 编码，仅本次使用，不落库不落盘）。证书将写入实例的 debug_ramdisk/secure.prop 文件。

URL: /container_api/v1/update_cert
方式: POST

参数:

参数名	类型	必选	说明
db_id	string	是	实例唯一标识（EDGE + 12位随机字符）
cert_hash	string	否	证书文件哈希值（优先使用）。必须已通过证书管理接口导入到系统，且文件必须存在于 `/etc/secure/<cert_hash>` 路径。如果同时提供了 cert_hash 和 cert_content，优先使用 cert_hash
cert_content	string	否	证书内容的 base64 编码（当未提供 cert_hash 时使用）。仅本次操作使用，不落库不落盘，将直接写入实例的 debug_ramdisk/secure.prop 文件。支持 secure.prop 格式或 XML 格式（会自动转换为 prop 格式）

说明: cert_hash 和 cert_content 必须提供其中一个

请求示例:

json

{
  "db_id": "EDGE0A1B2C3D4E5",
  "cert_hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
}

更新用户属性

批量更新指定实例的用户自定义安卓属性。

URL: /container_api/v1/update_user_prop
方式: POST

参数:

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例唯一标识列表（EDGE + 12位随机字符，支持批量操作）
user_prop	string	是	用户自定义安卓属性（JSON 格式字符串）。例如：`{"ro.product.model":"CustomModel","ro.build.version.sdk":"33"}`
preset_prop	object	否	预置属性映射，由客户端的预置属性选项生成
isRestart	boolean	否	是否在更新属性后重启实例（可选，默认 false）。当设置为 true 时，会在后台异步重启所有实例

请求示例:

json

{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9I0J1"],
  "user_prop": "{\"ro.product.model\":\"CustomModel\",\"ro.build.version.sdk\":\"33\"}",
  "isRestart": false
}

设置IP

修改实例IP（仅macvlan模式）。仅接受 macvlan 模式的实例，修改其 LAN IP。修改前会检查 db_id 是否存在以及 IP 是否已被占用。

URL: /container_api/v1/set_ip
方式: POST
参数:
参数名类型必选说明
db_id string 是实例唯一标识（EDGE + 12位随机字符）
ip string 是新的 LAN IP，需处于 macvlan 网段内

请求示例:

json

{
  "db_id": "EDGE0A1B2C3D4E5",
  "ip": "192.168.10.120"
}

获取实例详情

获取指定实例的详细信息。

URL: /container_api/v1/get_android_detail/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

获取实例列表

获取所有实例的列表。

URL: /container_api/v1/get_db
方式: POST

获取ADB命令

获取指定实例的ADB连接命令。

URL: /container_api/v1/adb_start/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

截图

获取指定实例的截图。

URL: /container_api/v1/screenshots/{db_id}
方式: GET

参数:

参数名	类型	必选	说明
db_id	string	是	实例唯一标识
format	string	否	图片格式：`jpg`、`png` 或 `webp`，默认 `jpg`
width	integer	否	目标宽度；与 `height` 均不传时返回原图
height	integer	否	目标高度；只传一个尺寸时按比例缩放
quality	integer	否	JPG/WebP 缩放后的图片质量
no_cache	boolean	否	传 `true` 跳过服务端短时缓存

克隆实例

克隆指定实例。

URL: /container_api/v1/clone
方式: POST

参数:

参数名	类型	必选	说明
user_name	string	是	克隆出来的实例名
db_id	string	是	被克隆的容器 db_id
count	integer	是	克隆数量，最大为 12
update_prop	boolean	否	是否在克隆完成后自动刷新安卓属性，默认 false。true 时按源实例 country 生成随机 androidProp

请求示例:

json

{
  "user_name": "test-001",
  "db_id": "EDGE0A1B2C3D4E5",
  "count": 1,
  "update_prop": true
}

克隆实例任务状态

查询克隆实例任务状态。

URL: /container_api/v1/clone_status
方式: GET

获取ROM状态

查询实例 ROM 是否已启动就绪。

URL: /container_api/v1/rom_status/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识
返回值说明:
code msg 说明
0 实例未启动就绪实例未启动
1 ROM未就绪实例运行中但ROM未就绪
200 ROM已就绪 ROM就绪

code	msg	说明
0	实例未启动就绪	实例未启动
1	ROM未就绪	实例运行中但ROM未就绪
200	ROM已就绪	ROM就绪

查询所有容器ID

返回所有实例的 db_id/user_name/adb 列表。

URL: /container_api/v1/list_names
方式: GET

同步实例状态

同步实例状态。

URL: /container_api/v1/sync_status
方式: GET

批量一键新机（异步）

仅允许 running 或 stopped。置 state=renewing 后异步执行停机→清数据→启动；保留 db_id 与 user_name。

URL: /container_api/v1/replace_devinfo
方式: POST

参数:

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例唯一标识列表
adiID	integer	否	ADI 模板ID（优先级最高，通过 /v1/get_adi_list 获取可用模板ID），系统会自动查找对应的模板文件和密码
adiName	string	否	ADI模板文件名（如果传了adiID，可以不用传adiName和adiPass）
adiPass	string	否	ADI解压密码（如果传了adiID，可以不用传adiName和adiPass）
country	string	否	随机生成安卓属性时使用的国家代码（ISO Alpha-2），如 CN。未填写时优先根据实例 locale 推断，否则默认 CN
userProp	string	否	自定义安卓属性（JSON 格式字符串）
wipeData	boolean	否	是否清空数据盘并重置 debug_ramdisk，默认 true。false 时仅刷新配置并保留数据
lon	float	否	经度。例如 121.5
lat	float	否	纬度。例如 31.2
locale	string	否	语言。例如 zh-CN
timezone	string	否	时区。例如 Asia/Shanghai
cert_hash	string	否	证书文件哈希值（优先使用）。必须已通过证书管理接口导入到系统
cert_content	string	否	证书内容的 base64 编码（当未提供 cert_hash 时使用）。仅本次操作使用，不落库不落盘
scdArgs	string	否	一键新机后使用的 SCD 推流配置 JSON 字符串

请求示例:

json

{
  "db_ids": ["EDGE0A1...", "EDGE6F7..."],
  "adiID": 1039,
  "country": "CN",
  "wipeData": true,
  "userProp": "{\"persist.sys.country\":\"CN\"}",
  "lon": 121.5,
  "lat": 31.2,
  "locale": "zh-CN",
  "timezone": "Asia/Shanghai",
  "cert_hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
}

批量更新停止实例镜像信息

批量更新停止实例的镜像信息。仅处理 stopped/failed 状态的实例。

URL: /container_api/v1/update_stopped_image
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是 db_id 数组（支持单个或多个）
repository string 是镜像仓库名（不含tag，默认使用latest）

参数名	类型	必选	说明
db_ids	`array<string>`	是	db_id 数组（支持单个或多个）
repository	string	是	镜像仓库名（不含tag，默认使用latest）

请求示例:

json

{
  "db_ids": ["EDGE0A1...", "EDGE6F7..."],
  "repository": "vcloud_android13_edge_20250925011125"
}

更新投屏服务

更新投屏服务。

URL: /container_api/v1/refreshScreenService
方式: POST
Content-Type: multipart/form-data

参数:

参数名	类型	必选	说明
file	`array<file>`	是	上传的文件（支持 scd 或 scd.sh，可同时上传多个）
db_id	string	否	实例ID（可选，与 user_name 二选一）
user_name	string	否	用户名（可选，与 db_id 二选一）

启动GMS

启动所有实例的GMS服务。

URL: /container_api/v1/gms_start
方式: GET

停用GMS

停用所有实例的GMS服务。

URL: /container_api/v1/gms_stop
方式: GET

生成设备机型备份

备份指定实例的设备机型环境信息，用于在不同实例之间迁移设备基础环境。备份内容包括设备机型、设备名称及 Android 侧关键设备标识，不包含 APK、应用私有数据、业务账号数据。

URL: /container_api/v1/model_backup/{db_id}
方式: POST
前提条件: 实例状态必须为 stopped / exited / failed
参数:
参数名类型必选说明
db_id string 是源实例 ID（路径参数）
name string 是备份文件名，建议使用 .zip 后缀

参数名	类型	必选	说明
db_id	string	是	源实例 ID（路径参数）
name	string	是	备份文件名，建议使用 `.zip` 后缀

请求示例:

bash

curl -X POST 'http://<盒子IP>:18182/container_api/v1/model_backup/EDGENQM4QQCVS014' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "demo_model_backup.zip"
  }'

返回示例:

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "host_ip": "192.168.10.35",
    "db_id": "EDGENQM4QQCVS014",
    "file": "demo_model_backup.zip",
    "path": "/container_nswc_lv/model_backup/demo_model_backup.zip",
    "size": 25152641,
    "debug_ramdisk_files": 544,
    "identity_files": 3,
    "target_instance_name": "EDGENQM4QQCVS014"
  }
}

说明: 备份文件默认存放在盒子本地目录 /container_nswc_lv/model_backup/

恢复设备机型备份

将备份的设备机型环境信息恢复到目标实例。支持通过备份文件名或绝对路径指定备份文件。

URL: /container_api/v1/model_restore/{db_id}
方式: POST
前提条件: 目标实例状态必须为 stopped / exited / failed

参数:

参数名	类型	必选	说明
db_id	string	是	目标实例 ID（路径参数）
name	string	否	盒子本地备份库中的备份文件名（与 path 二选一）
path	string	否	备份 ZIP 的绝对路径（与 name 二选一）

按备份名恢复示例:

bash

curl -X POST 'http://<盒子IP>:18182/container_api/v1/model_restore/EDGEUVEPN3IUSEQP' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "demo_model_backup.zip"
  }'

按绝对路径恢复示例:

bash

curl -X POST 'http://<盒子IP>:18182/container_api/v1/model_restore/EDGEUVEPN3IUSEQP' \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "/container_nswc_lv/model_backup/demo_model_backup.zip"
  }'

返回示例:

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "host_ip": "192.168.10.35",
    "db_id": "EDGEUVEPN3IUSEQP",
    "source_backup_name": "demo_model_backup",
    "debug_ramdisk_files": 544,
    "identity_files": 3,
    "warnings": []
  }
}

说明: 如果源备份和目标实例的镜像或 Android 版本存在差异，返回中可能包含 warnings。建议优先在相同 Android 大版本环境下使用

接口日志 (API Logs)

查询最近接口日志

返回最近20条接口执行记录。

URL: /interface_logs/recent
方式: GET

显示日志详情

显示日志详情。

URL: /interface_logs/detail
方式: GET

接口成功率查询

统计各接口执行次数与成功率。

URL: /interface_logs/stats
方式: GET

应用管理 (App)

获取应用列表

获取实例中已安装的第三方应用包名列表。

URL: /android_api/v1/app_get/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

启动应用（批量）

批量启动指定实例中的应用。

URL: /android_api/v1/app_start
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID列表，支持批量操作
app string 是应用包名（单个）

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID列表，支持批量操作
app	string	是	应用包名（单个）

请求示例:

json

{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9J0K1"],
  "app": "com.chartcross.gpstest"
}

停止应用（批量）

批量关闭指定实例中的应用。

URL: /android_api/v1/app_stop
方式: POST
参数:
参数名类型必选说明
db_ids array<string> 是实例ID列表，支持批量操作
app string 是应用包名（单个）

参数名	类型	必选	说明
db_ids	`array<string>`	是	实例ID列表，支持批量操作
app	string	是	应用包名（单个）

请求示例:

json

{
  "db_ids": ["EDGE0A1B2C3D4E5", "EDGE6F7G8H9J0K1"],
  "app": "com.tencent.mm"
}

设置应用Root权限

批量授予指定实例中应用的Root权限。操作完需要重启应用才能生效。

URL: /android_api/v1/root_app
方式: POST

参数:

参数名	类型	必选	说明
db_ids	string	是	实例ID列表，支持中文逗号（，）和英文逗号（,）分隔，如 EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1 或 EDGE0A1B2C3D4E5，EDGE6F7G8H9J0K1
app	string	是	需要授予 Root 权限的包名（须已安装）

请求示例:

json

{
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1",
  "app": "com.chartcross.gpstest"
}

添加显示在其他应用上层权限

为指定应用启用显示在其他应用上层的权限（悬浮窗权限）。

URL: /android_api/v1/add_show_other_app_over_permission
方式: POST
参数:
参数名类型必选说明
db_id string 是实例ID
app string 是应用包名

参数名	类型	必选	说明
db_id	string	是	实例ID
app	string	是	应用包名

请求示例:

json

{
  "db_id": "EDGEH06HF5E52NQL",
  "app": "com.zhiliaoapp.musically"
}

文件操作 (File)

批量安装APK

通过上传文件的方式批量安装到指定的安卓容器。支持单包APK和Split APK（多包）。

URL: /android_api/v1/upload_file_android_batch
方式: POST
Content-Type: multipart/form-data

参数:

参数名	类型	必选	说明
db_ids	string	是	实例ID列表，多个用逗号分隔，如 EDGE123,EDGE456
file	file	是	安装包文件：支持单包 .apk；或 split apk 的 .zip/.xapk/.tar/.tar.gz/.tgz（解压后含多个 .apk，xapk 格式解压方式同 zip）

批量上传文件

通过上传本地文件的方式批量复制至实例指定目录。

URL: /android_api/v1/upload_file_android_upload
方式: POST
Content-Type: multipart/form-data

参数:

参数名	类型	必选	说明
db_ids	string	是	实例ID列表，多个用逗号分隔（支持中文逗号，和英文逗号,），如 EDGE123,EDGE456 或 EDGE123，EDGE456
file	file	是	要上传的文件
path	string	否	可选，目标目录，默认 /storage/emulated/0/Download

从URL批量安装APK

通过URL下载APK文件并批量安装到指定的安卓容器。

URL: /android_api/v1/install_apk_from_url_batch
方式: POST
参数:
参数名类型必选说明
url string 是 APK文件下载URL
db_ids string 是实例ID列表，多个用逗号分隔（支持中文逗号，和英文逗号,），如 EDGE123,EDGE456 或 EDGE123，EDGE456

参数名	类型	必选	说明
url	string	是	APK文件下载URL
db_ids	string	是	实例ID列表，多个用逗号分隔（支持中文逗号，和英文逗号,），如 EDGE123,EDGE456 或 EDGE123，EDGE456

请求示例:

json

{
  "url": "https://example.com/app.apk",
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1"
}

从URL批量上传文件

通过URL下载文件并批量复制至实例指定目录。

URL: /android_api/v1/upload_file_from_url_batch
方式: POST

参数:

参数名	类型	必选	说明
url	string	是	文件的下载URL
db_ids	string	是	实例ID列表，多个用逗号分隔（支持中文逗号，和英文逗号,），如 EDGE123,EDGE456 或 EDGE123，EDGE456
path	string	否	可选，目标目录，默认 /storage/emulated/0/Download

请求示例:

json

{
  "url": "https://example.com/file.zip",
  "db_ids": "EDGE0A1B2C3D4E5,EDGE6F7G8H9J0K1",
  "path": "/storage/emulated/0/Download"
}

导出手机APK

从指定实例中导出已安装应用的APK文件，通过浏览器下载。

URL: /android_api/v1/export_phone_apk
方式: POST
参数:
参数名类型必选说明
db_id string 是实例ID
app string 是应用包名
说明:
- 单 APK：返回 [app].apk
- Split APK（多包）：返回 [app]_apks.zip（包含多份APK）
- 浏览器会自动触发下载，用户可以选择保存路径

参数名	类型	必选	说明
db_id	string	是	实例ID
app	string	是	应用包名

请求示例:

json

{
  "db_id": "EDGEH06HF5E52NQL",
  "app": "com.zhiliaoapp.musically"
}

系统控制 (System)

执行ADB命令

执行自定义ADB Shell命令。

URL: /android_api/v1/shell/{db_id}
方式: POST
参数:
参数名类型必选说明
db_id string 是实例唯一标识
cmd string 是要执行的shell命令（请求体）

停止前台应用

自动获取当前前台应用的包名并使用 am force-stop 命令强制关闭应用。

URL: /android_api/v1/stop_front_app/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

GPS注入

向安卓容器注入GPS定位信息。

URL: /android_api/v1/gps_inject/{db_id}
方式: POST
路径参数:
参数名类型必选说明
db_id string 是实例唯一标识（EDGE + 12位随机字符）

请求体参数:

参数名	类型	必选	说明
longitude	float	是	经度。范围：-180.0 ~ 180.0，东经为正，西经为负。示例：116.397455（北京天安门）
latitude	float	是	纬度。范围：-90.0 ~ 90.0，北纬为正，南纬为负。示例：39.909187（北京天安门）
altitude	float	否	海拔高度。单位：米（m）。表示相对于海平面的高度。示例：8
speed	float	否	移动速度。单位：米/秒（m/s）。表示设备的移动速度。示例：8（约 28.8 km/h）
bearing	float	否	方位角/航向。单位：度（°）。范围：0.0 ~ 360.0，表示设备移动的方向。0° 为正北，90° 为正东，180° 为正南，270° 为正西
horizontalAccuracyMeters	float	否	水平定位精度。单位：米（m）。表示定位的精确程度，值越小表示越精确。示例：0.1（精度 10 厘米）

请求示例:

json

{
  "longitude": 116.397455,
  "latitude": 39.909187,
  "altitude": 43.5,
  "speed": 0,
  "bearing": 0,
  "horizontalAccuracyMeters": 5.0
}

视频注入

设置视频注入。

URL: /android_api/v1/video_inject/{db_id}
方式: POST
路径参数:
参数名类型必选说明
db_id string 是容器ID
请求体参数:
参数名类型必选说明
url string 是视频URL

参数名	类型	必选	说明
db_id	string	是	容器ID

参数名	类型	必选	说明
url	string	是	视频URL

请求示例:

json

{
  "url": "https://example.com/demo.mp4"
}

关闭视频注入

关闭视频注入。

URL: /android_api/v1/video_inject_off/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

设置时区

设置实例时区。

URL: /android_api/v1/timezone_set/{db_id}
方式: POST
路径参数:
参数名类型必选说明
db_id string 是容器ID
请求体参数:
参数名类型必选说明
timeZone string 是时区，例如 Asia/Shanghai。注意字段名中的大写 Z
请求示例:
json
```
{
  "timeZone": "Asia/Shanghai"
}
```

参数名	类型	必选	说明
db_id	string	是	容器ID

参数名	类型	必选	说明
timeZone	string	是	时区，例如 Asia/Shanghai。注意字段名中的大写 `Z`

设置国家

更新实例国家。

URL: /android_api/v1/country_set/{db_id}
方式: POST
路径参数:
参数名类型必选说明
db_id string 是实例唯一标识（EDGE + 12位随机字符）
请求体参数:
参数名类型必选说明
country string 是国家代码（country_info.json 内的 country_code），例如 CN、US、JP 等
常见国家代码:
国家代码国家代码
中国 CN 美国 US
德国 DE 印度 IN
日本 JP 英国 GB
法国 FR 意大利 IT
加拿大 CA 巴西 BR
澳大利亚 AU 西班牙 ES
韩国 KR 荷兰 NL
请求示例:
json
```
{
  "country": "CN"
}
```

设置语言

设置实例语言。

URL: /android_api/v1/language_set/{db_id}
方式: POST
路径参数:
参数名类型必选说明
db_id string 是容器ID
请求体参数:
参数名类型必选说明
country string 是国家代码，例如 CN
language string 是语言代码，例如 zh

请求示例:

json

{
  "country": "CN",
  "language": "zh"
}

查询实例国家、语言、时区

获取实例的国家、语言、时区信息。

URL: /android_api/v1/get_timezone_locale/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是实例唯一标识

根据IP获取经纬度

根据实例或代理IP查询经纬度。

URL: /android_api/v1/ip_geo/{db_id}
方式: GET
参数:
参数名类型必选说明
db_id string 是容器ID
ip string 否可选，覆盖查询的IP

证书管理 (Certificate)

从文件导入证书

通过上传证书文件的方式导入证书到系统。支持一次上传多个证书文件，系统会自动计算证书内容的 SHA-256 哈希值作为文件名保存。

URL: /certificate_manage/file_import_cert
方式: POST
Content-Type: multipart/form-data
支持的文件格式: .crt, .pem, .cer, .cert（标准证书格式）、.key（私钥文件）、.prop（secure.prop 格式）、.xml（XML 格式，会自动转换为 prop 格式）

参数:

参数名	类型	必选	说明
file	`array<file>`	是	证书文件（支持多个文件）
filename	string	否	文件名（可选，支持单个或多个，多个用逗号分隔，支持中文逗号，和英文逗号,）

从文本导入证书

通过传递证书文本内容（base64编码）的方式导入证书到系统。系统会自动检测证书格式（XML 或 prop 格式），XML 格式会自动转换为 prop 格式。

URL: /certificate_manage/content_import_cert
方式: POST
参数:
参数名类型必选说明
content string 是 Base64 编码的证书内容（必填）
支持的内容格式: secure.prop 格式（标准格式）、XML 格式（会自动转换为 prop 格式）

请求示例:

json

{
  "content": "cm8uYnVpbGQuY2xvdWQuZ21zX3N1aXRlX2Rpc2FibGVkPTE="
}

SSD管理 (SSD)

存储状态

返回启动时扫描的存储状态：trial（试用，无SSD）、new_ssd（发现新SSD，需操作）、ssd（已登记并挂载）。

URL: /storage/status
方式: GET

格式化为数据盘并挂载

将指定设备格式化为 ext4 并挂载至 /container_nswc_lv，写入 fstab(UUID)。

URL: /storage/format
方式: POST
参数:
参数名类型必选说明
device string 是设备路径，如 /dev/nvme0n1 或其分区
confirm boolean 是确认操作

请求示例:

json

{
  "device": "/dev/nvme0n1",
  "confirm": true
}

导入现有数据盘并挂载

不格式化，直接挂载指定设备为 /container_nswc_lv。

URL: /storage/import
方式: POST
参数:
参数名类型必选说明
device string 是设备路径
confirm boolean 是确认操作

请求示例:

json

{
  "device": "/dev/nvme0n1",
  "confirm": true
}

版本更新 (Update)

CBS版本更新

上传CBS可执行文件并更新服务，更新后请刷新页面。

URL: /v1/update_cbs
方式: POST
Content-Type: multipart/form-data
文件命名要求: 必须是 cbs_go_edge_version 格式，支持'无后缀可执行文件'或 .cbs 后缀；不支持 .exe
参数:
参数名类型必选说明
file file 是 CBS可执行文件（文件名必须是 cbs_go_edge_version 格式；支持无后缀或 .cbs，不支持 .exe）
返回值说明:
字段说明
code 200 成功；0 失败
msg 操作结果说明
data.host_ip 主机 IP
data.current_version 当前运行的版本号

内核版本更新

上传内核镜像文件并更新系统内核，更新后主机会自动重启。

URL: /v1/update_kernel
方式: POST
Content-Type: multipart/form-data
文件命名要求: 必须是 .img 格式镜像文件
执行流程:
1. 上传的 .img 文件保存到 /userdata/new_boot.img
2. 自动设置文件可执行权限（0755）
3. 执行内核刷写命令并重启系统
参数:
参数名类型必选说明
file file 是内核镜像文件（必须是 .img 格式）
返回值说明:
字段说明
code 200 成功；0 失败
msg 操作结果说明
data.host_ip 主机 IP

桌面客户端扩展能力 (Desktop-integrated APIs)

以下接口已由 VMOS Edge Desktop 2.2.8 集成，并作为 Container API 对外能力补充。实际可用性取决于 CBS 版本；接入前应先查询版本。大多数接口使用本文开头的通用 JSON 结构，转发类接口的 msg / message 和 data 字段可能由云机服务直接透传。

主机网络配置

查询当前网络配置

URL: /sys/network/config
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "interface": "eth0",
    "ip": "192.168.10.20",
    "netmask": "255.255.255.0",
    "gateway": "192.168.10.1",
    "dns": ["223.5.5.5"],
    "manual": true
  },
  "msg": "OK"
}

设置静态网络配置

URL: /sys/network/config
方式: POST
参数:
参数名类型必选说明
ip string 是主机静态 IP
netmask string 是子网掩码
gateway string 是默认网关
dns array<string> 否 DNS 服务器列表

请求示例:

json

{
  "ip": "192.168.10.20",
  "netmask": "255.255.255.0",
  "gateway": "192.168.10.1",
  "dns": ["223.5.5.5", "8.8.8.8"]
}

成功响应后主机地址可能立即变化。调用方应使用新 IP 重新执行心跳检查。

恢复 DHCP

URL: /sys/network/config/reset
方式: POST
参数: 无

设置 Swap 大小

URL: /v1/swap_size/{size_gb}
方式: GET
参数:
参数名类型必选说明
size_gb integer 是 Swap 大小，单位 GB，取值范围 2～16
说明: 本接口设置容量；/v1/swap/{enable} 设置开关，两者不可混用。

代理管理

设置代理

URL: /android_api/v1/proxy_set/{db_id}
方式: POST
路径参数: db_id 为实例 ID。

常用请求参数:

参数名	类型	必选	说明
ip	string	是	出口代理 IP 或域名
port	integer	是	代理端口
proxyName	string	否	协议类型：`http`、`socks5`、`shadowsocks`、`shadowsocksr`、`vmess` 或 `vless`；未传时服务端使用兼容默认值
account	string	否	用户名
password	string	否	密码
udpDisabled	boolean	否	是否禁用 UDP
dnsOverProxyDisabled	boolean	否	是否禁用代理 DNS
engineType	integer	否	代理引擎类型，默认 `0`
nodes	array	否	代理链节点，按中转节点到出口节点排列
proxyHash	string	否	调用方生成的代理配置标识

查询代理

URL: /android_api/v1/proxy_get/{db_id}
方式: GET
返回数据: data.proxy_config 为当前代理配置，data.engineType 为代理引擎类型。

关闭代理

URL: /android_api/v1/proxy_stop/{db_id}
方式: GET

完整备份

完整备份包含实例数据，与机型环境备份 model_backup / model_restore 不同。

导出完整备份

URL: /backup/export?db_id={db_id}
方式: GET
前提条件: 实例必须处于停止状态。
响应: 成功时返回 application/octet-stream；文件名通过 Content-Disposition 返回。失败时返回通用 JSON 错误。

取消备份

URL: /backup/cancel
方式: POST
请求示例:
json
```
{
  "db_id": "EDGE0A1B2C3D4E5"
}
```

导入完整备份

URL: /backup/import
方式: POST
Content-Type: multipart/form-data
参数:
参数名类型必选说明
file file 是完整备份文件；服务端支持 .tar 和 .tar.gz，Desktop 2.2.8 当前选择器只接受 .tar

多媒体注入状态与音频注入

Desktop 2.2.8 当前按视频或纯音频互斥模式使用这些接口，切换类型前会先关闭当前注入。服务端的视频注入接口还支持通过 injectType 选择 video、audio 或 both，是否可用取决于 CBS/云机版本。

查询视频注入状态

URL: /android_api/v1/getInjectStatus/{db_id}
方式: GET
返回数据: isInjecting、injectType、injectUrl。

音频注入

URL: /android_api/v1/audio_inject/{db_id}
方式: POST

请求示例:

json

{
  "injectUrl": "rtsp://192.168.10.8:8554/audio"
}

关闭音频注入

URL: /android_api/v1/audio_inject_off/{db_id}
方式: GET

查询音频注入状态

URL: /android_api/v1/getInjectAudioStatus/{db_id}
方式: GET
返回数据: isInjecting、source。

视频注入裁剪参数

POST /android_api/v1/video_inject/{db_id} 除必填的 url 外，还支持 injectCropMode（整数，当前值域 0、1、2）及 injectType（video、audio 或 both）。Desktop 2.2.8 当前发送 url 和 injectCropMode。

SCD 投屏配置

查询 SCD 配置

URL: /container_api/v1/scd_config/{db_id}
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "db_id": "EDGE0A1B2C3D4E5",
    "config": { "audio": "1" }
  },
  "msg": "OK"
}

更新 SCD 配置

URL: /container_api/v1/scd_config/{db_id}
方式: POST
请求示例:
json
```
{
  "scdArgs": "{\"audio\":\"1\"}"
}
```
说明: scdArgs 为必填字符串，可使用 JSON 对象字符串或空格分隔的 key=value，例如 audio=1 max_fps=30。不能直接把 { "audio": "1" } 作为顶层请求体。

重启 SCD

URL: /container_api/v1/scd_restart/{db_id}
方式: POST
参数: 无。更新配置后调用以使配置生效。

整盘迁移

整盘迁移是主机级高风险操作，应使用专用源盒子和目标盒子，并避免与实例生命周期任务并发执行。

查询迁移状态

URL: /disk_migration/v1/status
方式: GET

返回数据:

字段	类型	说明
stage	string	迁移阶段；常见值包括 `source_not_prepared`、`source_prepared`、`target_ready`、`restore_pending_restart`、`rollback_pending_restart` 和 `activated`，调用方应兼容新增值
ready	boolean	当前阶段是否已就绪
restart_required	boolean	是否需要重启
current_device_id	string	当前盒子设备标识
manifest.source_device_id	string	备份来源盒子标识
warnings	`array<string>`	非阻塞警告

准备源盘

URL: /disk_migration/v1/prepare
方式: POST
参数: 无

恢复目标盘

URL: /disk_migration/v1/restore
方式: POST
请求体: { "confirm": true }

回滚恢复

URL: /disk_migration/v1/rollback
方式: POST
请求体: { "confirm": true }

主机共享

加入共享

URL: /v1/share/open
方式: POST
请求体: { "url": "https://example.com/share-config" }

关闭共享

URL: /v1/share/close
方式: POST
参数: 无

SSH 远程调试隧道

隧道接口只应从可信局域网调用。返回的临时账号和密码属于敏感信息，不得写入日志或公开分享。

查询状态

URL: /tunnel/status
方式: GET
返回数据: 正常状态返回 state、locked、remote_port、expires_at、last_error、reconnect_count、enable_count、last_enable_at 和 healthy。降级状态还会返回稳定的 reason 与 hint。

解锁

URL: /tunnel/unlock
方式: POST
请求体: {}
访问限制: 请求来源必须为回环或 RFC1918 局域网地址，否则返回 HTTP 401。

开启隧道

URL: /tunnel/enable
方式: POST
请求体: {}
访问限制: 请求来源必须为回环或 RFC1918 局域网地址，否则返回 HTTP 401。
返回数据: password、remote_port 和 expires_at。password 仅在本次响应中返回一次；此时 remote_port 可能仍为 0，必须轮询 /tunnel/status 直到 state=connected 后取真实端口。SSH 用户名固定为 cbs_debug，不在响应中返回。

关闭隧道

URL: /tunnel/disable
方式: POST
请求体: {}
访问限制: 请求来源必须为回环或 RFC1918 局域网地址，否则返回 HTTP 401。
说明: 桌面客户端关闭后还会调用 /tunnel/unlock 清理锁状态。

Container API 接口文档 ​

简介 ​

调用方式 ​

1. HTTP 调用 ​

2. MCP 调用（AI Agent 集成） ​

3. Skills 调用（AI Agent 集成） ​

通用响应结构 ​

主机管理 (Host) ​

获取主机配置信息 ​

获取主机系统信息 ​

获取主机网络配置 ​

主机心跳检查 ​

获取主机镜像列表 ​

清理未使用镜像 ​

导入镜像 ​

设置Swap开关 ​

重启主机 ​

主机关机 ​

重置主机 ​

发现服务状态 ​

导入机型模板 ​

获取主机机型模板列表 ​

实例管理 (Instance) ​

创建实例 ​

批量启动实例（异步） ​

批量停止实例（异步） ​

批量重启实例（异步） ​

批量重置实例（异步） ​

批量删除实例（异步） ​

升级实例镜像 ​

重命名实例 ​

更新证书配置 ​

更新用户属性 ​

设置IP ​

获取实例详情 ​

获取实例列表 ​

获取ADB命令 ​

截图 ​

克隆实例 ​

克隆实例任务状态 ​

获取ROM状态 ​

查询所有容器ID ​

同步实例状态 ​

批量一键新机（异步） ​

批量更新停止实例镜像信息 ​

更新投屏服务 ​

启动GMS ​

停用GMS ​

生成设备机型备份 ​

恢复设备机型备份 ​

接口日志 (API Logs) ​

查询最近接口日志 ​

显示日志详情 ​

接口成功率查询 ​

应用管理 (App) ​

获取应用列表 ​

启动应用（批量） ​

停止应用（批量） ​

设置应用Root权限 ​

添加显示在其他应用上层权限 ​

文件操作 (File) ​

批量安装APK ​

批量上传文件 ​

从URL批量安装APK ​

从URL批量上传文件 ​

导出手机APK ​

系统控制 (System) ​

执行ADB命令 ​

停止前台应用 ​

GPS注入 ​

视频注入 ​

关闭视频注入 ​

设置时区 ​

设置国家 ​

设置语言 ​

查询实例国家、语言、时区 ​

根据IP获取经纬度 ​

证书管理 (Certificate) ​

从文件导入证书 ​

从文本导入证书 ​

Container API 接口文档

简介

调用方式

1. HTTP 调用

2. MCP 调用（AI Agent 集成）

3. Skills 调用（AI Agent 集成）

通用响应结构

主机管理 (Host)

获取主机配置信息

获取主机系统信息

获取主机网络配置

主机心跳检查

获取主机镜像列表

清理未使用镜像

导入镜像

设置Swap开关

重启主机

主机关机

重置主机

发现服务状态

导入机型模板

获取主机机型模板列表

实例管理 (Instance)

创建实例

批量启动实例（异步）

批量停止实例（异步）

批量重启实例（异步）

批量重置实例（异步）

批量删除实例（异步）

升级实例镜像

重命名实例

更新证书配置

更新用户属性

设置IP

获取实例详情

获取实例列表

获取ADB命令

截图

克隆实例

克隆实例任务状态

获取ROM状态

查询所有容器ID

同步实例状态

批量一键新机（异步）

批量更新停止实例镜像信息

更新投屏服务

启动GMS

停用GMS

生成设备机型备份

恢复设备机型备份

接口日志 (API Logs)

查询最近接口日志

显示日志详情

接口成功率查询

应用管理 (App)

获取应用列表

启动应用（批量）

停止应用（批量）

设置应用Root权限

添加显示在其他应用上层权限

文件操作 (File)

批量安装APK

批量上传文件

从URL批量安装APK

从URL批量上传文件

导出手机APK

系统控制 (System)

执行ADB命令

停止前台应用

GPS注入

视频注入

关闭视频注入

设置时区

设置国家

设置语言

查询实例国家、语言、时区

根据IP获取经纬度

证书管理 (Certificate)

从文件导入证书

从文本导入证书