盒子内SDK API 开发文档
MYT-SDK API 接口文档
更新日期 2026-1-16
📌 接口说明
访问地址: http://{主机IP}:8000/swagger
- 主机IP:设备的网络IP地址(例如:192.168.99.108)
- 端口:固定为 8000
- 协议:HTTP
响应格式:所有接口统一返回JSON格式
{
"code": 0,
"message": "ok",
"data": { ... }
}
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码,0表示成功,非0表示失败 |
| message | string | 状态信息 |
| data | object | 返回数据 |
📚 接口目录
一、基本信息
1. 获取API版本信息
功能说明:获取当前API版本信息
请求方式:GET
请求URL:
http://{主机IP}:8000/info
请求参数:无
请求示例:
curl "http://192.168.99.108:8000/info"
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"latestVersion": 110,
"currentVersion": 108
}
}
返回字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| latestVersion | int | 线上最新版本号 |
| currentVersion | int | 当前本地版本号 |
失败返回:
{
"code": 500,
"message": "获取版本信息失败",
"data": null
}
注意事项:
- 当 currentVersion < latestVersion 时,建议更新SDK
2. 获取设备基本信息
功能说明:获取当前设备的硬件和系统信息
请求方式:GET
请求URL:
http://{主机IP}:8000/info/device
请求参数:无
请求示例:
curl "http://192.168.99.108:8000/info/device"
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"ip": "192.168.99.108",
"ip_1": "192.168.100.108",
"hwaddr": "AA:BB:CC:DD:EE:FF",
"hwaddr_1": "AA:BB:CC:DD:EE:F1",
"cputemp": 45,
"cpuload": "1.5",
"memtotal": "8GB",
"memuse": "4.2GB",
"mmctotal": "256GB",
"mmcuse": "120GB",
"version": "v1.1.0",
"deviceId": "MYT-P1-001",
"model": "P1",
"speed": "1000Mbps",
"mmcread": "150MB/s",
"mmcwrite": "120MB/s",
"sysuptime": "10天5小时",
"mmcmodel": "Samsung EVO",
"mmctemp": "38",
"network4g": "未连接",
"netWork_eth0": "已连接"
}
}
返回字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| ip | string | 网口IP |
| ip_1 | string | 网口1的IP |
| hwaddr | string | MAC地址 |
| hwaddr_1 | string | MAC1地址 |
| cputemp | int | CPU温度 |
| cpuload | string | CPU负载 |
| memtotal | string | 内存总大小 |
| memuse | string | 内存已使用大小 |
| mmctotal | string | 磁盘总大小 |
| mmcuse | string | 磁盘已使用大小 |
| version | string | 固件版本 |
| deviceId | string | 设备ID |
| model | string | 型号版本 |
| speed | string | 网口速率 |
| mmcread | string | 磁盘读取量 |
| mmcwrite | string | 磁盘写入量 |
| sysuptime | string | 设备运行时间 |
| mmcmodel | string | 磁盘型号 |
| mmctemp | string | 磁盘温度 |
| network4g | string | 4G网卡状态 |
| netWork_eth0 | string | ETH0网卡状态 |
失败返回:
{
"code": 500,
"message": "获取设备信息失败",
"data": null
}
二、云机操作
1. 获取安卓云机列表
功能说明:获取设备上所有安卓云机容器列表
请求方式:GET
请求URL:
http://{主机IP}:8000/android
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 否 | string | 根据云机名过滤 |
| running | 否 | bool | 根据云机是否运行过滤,false查询所有 |
| indexNum | 否 | int | 根据云机实例位序号过滤(0-24) |
请求示例:
# 获取所有云机
curl "http://192.168.99.108:8000/android"
# 根据名称过滤
curl "http://192.168.99.108:8000/android?name=test"
# 只获取运行中的云机
curl "http://192.168.99.108:8000/android?running=true"
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"count": 2,
"list": [
{
"id": "abc123def456",
"name": "android-01",
"status": "running",
"indexNum": 1,
"dataPath": "/myt/data/android-01",
"modelPath": "/myt/model/android-01",
"image": "registry.example.com/android:v12",
"ip": "192.168.100.101",
"networkName": "myt_bridge",
"portBindings": {},
"dns": "223.5.5.5",
"doboxFps": "60",
"doboxWidth": "1080",
"doboxHeight": "1920",
"doboxDpi": "480",
"mgenable": "0",
"gmsenable": "0",
"s5User": "",
"s5Password": "",
"s5IP": "",
"s5Port": "",
"s5Type": "0",
"created": "2024-01-15 10:30:00",
"started": "2024-01-15 10:31:00",
"finished": "",
"customBinds": [],
"PINCode": ""
}
]
}
}
返回字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 云机容器ID |
| name | string | 云机名称 |
| status | string | 状态(running/stopped) |
| indexNum | int | 云机实例位序号 |
| dataPath | string | 云机Data文件在设备里的路径 |
| modelPath | string | 云机机型文件在设备里的路径 |
| image | string | 云机所用的镜像 |
| ip | string | 云机局域网IP |
| networkName | string | 容器网卡名称 |
| dns | string | 云机DNS |
| doboxFps | string | 云机FPS |
| doboxWidth | string | 云机分辨率的宽 |
| doboxHeight | string | 云机分辨率的高 |
| doboxDpi | string | 云机DPI |
| mgenable | string | magisk开关,0-关,1-开 |
| gmsenable | string | gms开关,0-关,1-开 |
| s5User | string | s5代理用户名 |
| s5Password | string | s5代理密码 |
| s5IP | string | s5代理IP |
| s5Port | string | s5代理端口 |
| s5Type | string | 代理类型,0-不开启,1-本地域名解析,2-服务器域名解析 |
| created | string | 云机容器创建时间 |
| started | string | 云机容器上次开启时间 |
| finished | string | 云机容器上次关闭时间 |
| customBinds | array | 自定义文件映射 |
| PINCode | string | 自定义屏幕锁屏密码 |
失败返回:
{
"code": 500,
"message": "获取云机列表失败",
"data": null
}
2. 创建安卓云机
功能说明:创建一个新的安卓云机容器
请求方式:POST
请求URL:
http://{主机IP}:8000/android
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
| imageUrl | 是 | string | 镜像完整地址 |
| dns | 是 | string | 云机DNS,例如223.5.5.5 |
| modelId | 否 | string | 线上机型ID |
| modelName | 否 | string | 线上机型名称 |
| LocalModel | 否 | string | 本地机型名称 |
| modelStatic | 否 | string | 本地静态机型 名称(优先级最高) |
| indexNum | 否 | int | 实例序号,P1范围1-24,Q1范围1-12,传0自动分配 |
| sandboxSize | 否 | string | 沙盒大小,例如16GB,32GB |
| offset | 否 | string | 云机的开机时间 |
| doboxFps | 否 | string | 云机FPS |
| doboxWidth | 否 | string | 云机分辨率的宽 |
| doboxHeight | 否 | string | 云机分辨率的高 |
| doboxDpi | 否 | string | 云机DPI |
| network | 否 | object | 独立IP设置 |
| start | 否 | bool | 创建完成是否开机,默认true |
| mgenable | 否 | string | magisk开关,0-关,1-开,默认0 |
| gmsenable | 否 | string | gms开关,0-关,1-开,默认0 |
| latitude | 否 | float | 纬度 |
| longitude | 否 | float | 经度 |
| countryCode | 否 | string | 国家代码,例如CN,US |
| portMappings | 否 | array | 自定义端口映射 |
| s5User | 否 | string | s5代理用户名 |
| s5Password | 否 | string | s5代理密码 |
| s5IP | 否 | string | s5代理IP |
| s5Port | 否 | string | s5代理端口 |
| s5Type | 否 | string | 代理类型,0-不开启,1-tun2socks,2-tun2proxy |
| mytBridgeName | 否 | string | myt_bridge网卡名 |
| customBinds | 否 | array | 自定义文件映射 |
| PINCode | 否 | string | 屏幕锁屏密码,4-8位数字 |
network对象结构:
| 字段 | 类型 | 说明 |
|---|---|---|
| gw | string | 网关,例如192.168.100.1 |
| ip | string | 云机要设置的IP |
| subnet | string | 掩码,例如192.168.100.0/24 |
portMappings数组元素结构:
| 字段 | 类型 | 说明 |
|---|---|---|
| containerPort | int | 容器内端口 |
| hostPort | int | 主机端口 |
| hostIP | string | 主机IP |
| protocol | string | 协议(tcp/udp),默认tcp |
请求示例:
curl -X POST "http://192.168.99.108:8000/android" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01",
"imageUrl": "registry.example.com/android:v12",
"dns": "223.5.5.5",
"modelId": "1",
"indexNum": 1,
"doboxFps": "60",
"doboxWidth": "1080",
"doboxHeight": "1920",
"doboxDpi": "480",
"start": true
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"id": "abc123def456789"
}
}
失败返回:
{
"code": 500,
"message": "创建云机失败: 镜像不存在",
"data": null
}
注意事项:
- name必须唯一,不能与已有云机重名
- imageUrl必须是已拉取到本地的镜像地址
- indexNum范围:P1设备1-24,Q1设备1-12
- modelStatic优先级高于LocalModel和线上机型
3. 重置安卓云机
功能说明:重置指定的安卓云机
请求方式:PUT
请求URL:
http://{主机IP}:8000/android
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
| latitude | 否 | float | 纬度 |
| longitude | 否 | float | 经度 |
| countryCode | 否 | string | 国家代码,例如CN,US |
请求示例:
curl -X PUT "http://192.168.99.108:8000/android" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01",
"latitude": 39.9042,
"longitude": 116.4074,
"countryCode": "CN"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "重置云机失败: 云机不存在",
"data": null
}
注意事项:
- 重置会清除云机内的所有数据
- 重置前请确保已备份重要数据
4. 删除安卓云机
功能说明:删除指定的安卓云机容器
请求方式:DELETE
请求URL:
http://{主机IP}:8000/android
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
请求示例:
curl -X DELETE "http://192.168.99.108:8000/android" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "删除云机失败: 云机正在运行",
"data": null
}
注意事项:
- 删除操作不可恢复
- 建议删除前先停止云机
5. 切换安卓镜像
功能说明:切换云机使用的安卓镜像
请求方式:POST
请求URL:
http://{主机IP}:8000/android/switchImage
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
| imageUrl | 是 | string | 镜像完整地址 |
| modelId | 否 | string | 机型ID |
| LocalModel | 否 | string | 本地机型名称 |
| modelStatic | 否 | string | 本地静态机型名称 |
| dns | 否 | string | 云机DNS |
| offset | 否 | string | 云机的开机时间 |
| doboxFps | 否 | string | 云机FPS |
| doboxWidth | 否 | string | 云机分辨率的宽 |
| doboxHeight | 否 | string | 云机分辨率的高 |
| doboxDpi | 否 | string | 云机DPI |
| network | 否 | object | 独立IP设置 |
| start | 否 | bool | 切换完成是否开机,默认true |
| mgenable | 否 | string | magisk开关,0-关,1-开 |
| gmsenable | 否 | string | gms开关,0-关,1-开 |
| latitude | 否 | float | 纬度 |
| longitude | 否 | float | 经度 |
| countryCode | 否 | string | 国家代码 |
| s5User | 否 | string | s5代理用户名 |
| s5Password | 否 | string | s5代理密码 |
| s5IP | 否 | string | s5代理IP |
| s5Port | 否 | string | s5代理端口 |
| s5Type | 否 | string | 代理类型 |
| customBinds | 否 | array | 自定义文件映射 |
| PINCode | 否 | string | 屏幕锁屏密码 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/switchImage" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01",
"imageUrl": "registry.example.com/android:v13",
"start": true
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"message": "镜像切换成功"
}
}
失败返回:
{
"code": 500,
"message": "切换镜像失败: 镜像不存在",
"data": null
}
注意事项:
- 切换镜像会重置云机数据
- 确保目标镜像已拉取到本地
6. 切换机型
功能说明:切换云机的机型配置
请求方式:POST
请求URL:
http://{主机IP}:8000/android/switchModel
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
| modelId | 否 | string | 机型ID |
| localModel | 否 | string | 本地机型名称 |
| modelStatic | 否 | string | 本地静态机型名称 |
| latitude | 否 | float | 纬度 |
| longitude | 否 | float | 经度 |
| countryCode | 否 | string | 国家代码 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/switchModel" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01",
"modelId": "2",
"countryCode": "US"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "切换机型失败: 机型不存在",
"data": null
}
7. 拉取安卓镜像
功能说明:从镜像仓库拉取安卓镜像到本地
请求方式:POST
请求URL:
http://{主机IP}:8000/android/pullImage
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| imageUrl | 是 | string | 镜像完整地址 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/pullImage" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "registry.example.com/android:v12"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "拉取镜像失败: 网络连接超时",
"data": null
}
注意事项:
- 拉取镜像可能需要较长时间,取决于网络速度和镜像大小
- 确保设备有足够的磁盘空间
8. 启动安卓云机
功能说明:启动指定的安卓云机
请求方式:POST
请求URL:
http://{主机IP}:8000/android/start
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/start" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "启动云机失败: 云机已在运行",
"data": null
}
9. 关闭安卓云机
功能说明:关闭指定的安卓云机
请求方式:POST
请求URL:
http://{主机IP}:8000/android/stop
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/stop" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "关闭云机失败: 云机未运行",
"data": null
}
10. 重启安卓云机
功能说明:重启指定的安卓云机
请求方式:POST
请求URL:
http://{主机IP}:8000/android/restart
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 云机名称 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/restart" \
-H "Content-Type: application/json" \
-d '{
"name": "android-01"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "重启云机失败",
"data": null
}
11. 获取本地镜像列表
功能说明:获取设备上已拉取的Docker镜像列表
请求方式:GET
请求URL:
http://{主机IP}:8000/android/image
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| imageName | 否 | string | 根据镜像名过滤 |
请求示例:
curl "http://192.168.99.108:8000/android/image"
# 根据名称过滤
curl "http://192.168.99.108:8000/android/image?imageName=android"
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"count": 2,
"list": [
{
"id": "sha256:abc123",
"imageUrl": "registry.example.com/android:v12",
"size": "2.5GB",
"created": "2024-01-10 08:00:00",
"labels": {
"version": "12",
"type": "android"
}
},
{
"id": "sha256:def456",
"imageUrl": "registry.example.com/android:v13",
"size": "2.8GB",
"created": "2024-01-15 10:00:00",
"labels": {
"version": "13",
"type": "android"
}
}
]
}
}
返回字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 镜像ID |
| imageUrl | string | 镜像完整地址 |
| size | string | 镜像大小 |
| created | string | 创建时间 |
| labels | object | 镜像labels |
失败返回:
{
"code": 500,
"message": "获取镜像列表失败",
"data": null
}
12. 删除本地镜像
功能说明:删除设备上的本地Docker镜像
请求方式:DELETE
请求URL:
http://{主机IP}:8000/android/image
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| imageUrl | 是 | string | 要删除的镜像完整地址 |
请求示例:
curl -X DELETE "http://192.168.99.108:8000/android/image" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "registry.example.com/android:v12"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "删除镜像失败: 镜像正在被使用",
"data": null
}
注意事项:
- 正在被云机使用的镜像无法删除
- 删除前请确保没有云机依赖该镜像
13. 获取本地镜像压缩包列表
功能说明:获取设备上的镜像压缩包文件列表
请求方式:GET
请求URL:
http://{主机IP}:8000/android/imageTar
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| filename | 否 | string | 根据文件名过滤 |
请求示例:
curl "http://192.168.99.108:8000/android/imageTar"
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"count": 2,
"list": [
{
"name": "android_v12.tar",
"size": "2.5GB"
},
{
"name": "android_v13.tar",
"size": "2.8GB"
}
]
}
}
失败返回:
{
"code": 500,
"message": "获取镜像压缩包列表失败",
"data": null
}
14. 删除本地镜像压缩包
功能说明:删除设备上的镜像压缩包文件
请求方式:DELETE
请求URL:
http://{主机IP}:8000/android/imageTar
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| filename | 是 | string | 要删除的镜像压缩包名称 |
请求示例:
curl -X DELETE "http://192.168.99.108:8000/android/imageTar" \
-H "Content-Type: application/json" \
-d '{
"filename": "android_v12.tar"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "删除镜像压缩包失败: 文件不存在",
"data": null
}
15. 导出安卓镜像
功能说明:将本地镜像导出为压缩包文件
请求方式:POST
请求URL:
http://{主机IP}:8000/android/image/export
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| imageUrl | 是 | string | 要导出的镜像完整地址 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/image/export" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "registry.example.com/android:v12"
}'
成功返回:
{
"code": 0,
"message": "ok",
"data": {
"filename": "android_v12_20240115.tar"
}
}
失败返回:
{
"code": 500,
"message": "导出镜像失败: 磁盘空间不足",
"data": null
}
注意事项:
- 导出过程可能需要较长时间
- 确保设备有足够的磁盘空间
16. 下载导出后的安卓镜像包
功能说明:下载已导出的镜像压缩包文件
请求方式:GET
请求URL:
http://{主机IP}:8000/android/image/download
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| filename | 是 | string | 要下载的镜像包名 |
请求示例:
curl "http://192.168.99.108:8000/android/image/download?filename=android_v12.tar" -o android_v12.tar
成功返回:
- 返回文件的二进制数据,浏览器会自动下载
失败返回:
{
"code": 500,
"message": "下载失败: 文件不存在",
"data": null
}
17. 导入安卓镜像
功能说明:通过上传tar文件导入安卓镜像
请求方式:POST
请求URL:
http://{主机IP}:8000/android/image/import
Content-Type:multipart/form-data
请求参数:
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| file | 是 | file | 导入镜像包文件,tar格式 |
请求示例:
curl -X POST "http://192.168.99.108:8000/android/image/import" \
-F "file=@android_v12.tar"
成功返回:
{
"code": 0,
"message": "ok",
"data": {}
}
失败返回:
{
"code": 500,
"message": "导入镜像失败: 文件格式错误",
"data": null
}
注意事项:
- 仅支持tar格式的镜像包
- 导入过程可能需要较长时间
18. 导出安卓云机
功能说明:将安卓云机导出为压缩包
请求方式:POST
请求URL:
http://{主机IP}:8000/android/export