Container API 接口文档

更新时间: 2026年1月22日

简介

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

调用方式

1. HTTP 调用

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

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

通用响应结构

所有接口均返回标准 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
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
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 格式字符串）
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数组
返回值说明:
code 说明
200 成功，任务已入队
460 存在其他启动任务进行中
203 运行实例数量即将超限
1 db_id 不存在
2 实例不在 stopped 状态

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

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数组

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

批量重置实例（异步）

批量重置实例（异步）。

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

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

批量删除实例（异步）

批量删除实例（异步）。

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 解压密码

重命名实例

仅修改 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）

参数名	类型	必选	说明
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"}`
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 是实例唯一标识

参数名	类型	必选	说明
db_id	string	是	实例唯一标识

获取实例列表

获取所有实例的列表。

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

获取ADB命令

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

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

参数名	类型	必选	说明
db_id	string	是	实例唯一标识

截图

获取指定实例的截图。

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

参数名	类型	必选	说明
db_id	string	是	实例唯一标识

克隆实例

克隆指定实例。

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就绪

参数名	类型	必选	说明
db_id	string	是	实例唯一标识

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 时使用）。仅本次操作使用，不落库不落盘

请求示例:

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

接口日志 (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 是实例唯一标识

参数名	类型	必选	说明
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命令（请求体）

参数名	类型	必选	说明
db_id	string	是	实例唯一标识
cmd	string	是	要执行的shell命令（请求体）

停止前台应用

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

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

参数名	类型	必选	说明
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 是实例唯一标识

参数名	类型	必选	说明
db_id	string	是	实例唯一标识

设置时区

设置实例时区。

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

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

参数名	类型	必选	说明
timeZone	string	是	时区，例如 Asia/Shanghai

设置国家

更新实例国家。

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"
}
```

参数名	类型	必选	说明
country	string	是	国家代码（country_info.json 内的 country_code），例如 CN、US、JP 等

设置语言

设置实例语言。

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

Container API 接口文档 ​

简介 ​

调用方式 ​

1. HTTP 调用 ​

通用响应结构 ​

主机管理 (Host) ​

获取主机配置信息 ​

获取主机系统信息 ​

获取主机网络配置 ​

主机心跳检查 ​

获取主机镜像列表 ​

清理未使用镜像 ​

导入镜像 ​

设置Swap开关 ​

重启主机 ​

主机关机 ​

重置主机 ​

发现服务状态 ​

导入机型模板 ​

获取主机机型模板列表 ​

实例管理 (Instance) ​

创建实例 ​

批量启动实例（异步） ​

批量停止实例（异步） ​

批量重启实例（异步） ​

批量重置实例（异步） ​

批量删除实例（异步） ​

升级实例镜像 ​

重命名实例 ​

更新证书配置 ​

更新用户属性 ​

设置IP ​

获取实例详情 ​

获取实例列表 ​

获取ADB命令 ​

截图 ​

克隆实例 ​

克隆实例任务状态 ​

获取ROM状态 ​

查询所有容器ID ​

同步实例状态 ​

批量一键新机（异步） ​

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

更新投屏服务 ​

启动GMS ​

停用GMS ​

接口日志 (API Logs) ​

查询最近接口日志 ​

显示日志详情 ​

接口成功率查询 ​

应用管理 (App) ​

获取应用列表 ​

启动应用（批量） ​

停止应用（批量） ​

设置应用Root权限 ​

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

文件操作 (File) ​

批量安装APK ​

批量上传文件 ​

从URL批量安装APK ​

从URL批量上传文件 ​

导出手机APK ​

系统控制 (System) ​

执行ADB命令 ​

停止前台应用 ​

GPS注入 ​

视频注入 ​

关闭视频注入 ​

设置时区 ​

设置国家 ​

设置语言 ​

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

根据IP获取经纬度 ​

证书管理 (Certificate) ​

从文件导入证书 ​

从文本导入证书 ​

SSD管理 (SSD) ​

存储状态 ​

格式化为数据盘并挂载 ​

导入现有数据盘并挂载 ​

Container API 接口文档

简介

调用方式

1. HTTP 调用

通用响应结构

主机管理 (Host)

获取主机配置信息

获取主机系统信息

获取主机网络配置

主机心跳检查

获取主机镜像列表

清理未使用镜像

导入镜像

设置Swap开关

重启主机

主机关机

重置主机

发现服务状态

导入机型模板

获取主机机型模板列表

实例管理 (Instance)

创建实例

批量启动实例（异步）

批量停止实例（异步）

批量重启实例（异步）

批量重置实例（异步）

批量删除实例（异步）

升级实例镜像

重命名实例

更新证书配置

更新用户属性

设置IP

获取实例详情

获取实例列表

获取ADB命令

截图

克隆实例

克隆实例任务状态

获取ROM状态

查询所有容器ID

同步实例状态

批量一键新机（异步）

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

更新投屏服务

启动GMS

停用GMS

接口日志 (API Logs)

查询最近接口日志

显示日志详情

接口成功率查询

应用管理 (App)

获取应用列表

启动应用（批量）

停止应用（批量）

设置应用Root权限

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

文件操作 (File)

批量安装APK

批量上传文件

从URL批量安装APK

从URL批量上传文件

导出手机APK

系统控制 (System)

执行ADB命令

停止前台应用

GPS注入

视频注入

关闭视频注入

设置时区

设置国家

设置语言

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

根据IP获取经纬度

证书管理 (Certificate)

从文件导入证书

从文本导入证书

SSD管理 (SSD)

存储状态

格式化为数据盘并挂载

导入现有数据盘并挂载