Android Control API 接口文档

更新时间: 2026年1月9日

支持版本提示

Android Control API 需要特定的镜像版本支持，请确保您的云机镜像版本号不低于以下版本：

Android 10: vcloud_android10_edge_20260110 及以上
Android 13: vcloud_android13_edge_20260110 及以上
Android 15: vcloud_android15_edge_20260110 及以上
CBS: 1.1.1.10 及以上

简介

Android Control API 提供了 Android 系统的一系列操控与管理能力，涵盖了应用管理、输入控制、系统设置、文件操作等功能.

调用方式

1. 云机外HTTP调用

当您从宿主机或网络中的其他设备调用时，需要通过容器管理API进行转发：

URL 格式: http://{主机IP}:18182/android_api/v2/{云机ID}/{接口路径}
示例: http://192.168.1.100:18182/android_api/v2/EDGE12345678/activity/processes

2. 云机内HTTP调用

在安卓实例内部（如通过终端或内部脚本）直接调用：

URL 格式: http://127.0.0.1:18185/api/{接口路径}
示例: http://127.0.0.1:18185/api/activity/processes

3. Socket 调用

暂未开放，敬请期待。

4. 命令行 (CLI) 调用

暂未开放，敬请期待。

通用响应结构

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

json

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

逻辑处理 (Logic)

暂停响应

暂停接口响应一段时间。常用于脚本执行中的等待。需要镜像版本 20260113 及以上支持。

URL: /logic/sleep
方式: POST
参数:
参数名类型必选说明
duration long 是暂停时长 (ms)

参数名	类型	必选	说明
duration	long	是	暂停时长 (ms)

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sl123456"
}

工作流 (Workflow)

执行工作流

在单个请求中按顺序执行多个接口动作。需要镜像版本 20260113 及以上支持。

URL: /workflow
方式: POST
参数:
参数名类型必选说明
actions array 是动作列表。每个对象包含 path (接口路径) 和 params (参数对象)

参数名	类型	必选	说明
actions	array	是	动作列表。每个对象包含 `path` (接口路径) 和 `params` (参数对象)

请求示例:

json

{
  "actions": [
    {
      "path": "activity/start",
      "params": { "package_name": "com.android.settings" }
    },
    {
      "path": "logic/sleep",
      "params": { "duration": 2000 }
    },
    {
      "path": "input/click",
      "params": { "x": 500, "y": 800 }
    }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "request_id": "8aca36b28c444ca09d07fb2690d03a3d",
      "response_data": {
        "package_name": "com.android.settings",
        "class_name": "com.android.settings.Settings"
      }
    },
    {
      "request_id": "9bca36b28c444ca09d07fb2690d03a3e",
      "response_data": true
    },
    {
      "request_id": "0cca36b28c444ca09d07fb2690d03a3f",
      "response_data": { "x": 500, "y": 800 }
    }
  ],
  "msg": "OK",
  "request_id": "wf123456"
}

应用运行管理 (Activity)

启动应用

URL: /activity/start
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

请求示例:

json

{
  "package_name": "com.android.settings"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

启动指定 Activity

URL: /activity/start_activity
方式: POST

参数:

参数名	类型	必选	说明
package_name	string	否	应用包名 (指定了 action 时可选)
class_name	string	否	Activity 类名
action	string	否	Intent action
data	string	否	Intent data
extras	object	否	Intent extras (Key-Value 键值对)

请求示例:

json

{
  "package_name": "com.android.settings",
  "class_name": "com.android.settings.Settings",
  "extras": {
    "extra_key": "extra_value",
    "is_test": true
  }
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sa123456"
}

停止应用

URL: /activity/stop
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

请求示例:

json

{
  "package_name": "com.android.settings"
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

获取正在运行的进程

URL: /activity/processes
方式: GET

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "process_name": "com.android.settings",
      "pid": 1234,
      "uid": 1000,
      "package_names": ["com.android.settings"],
      "importance": 100
    }
  ],
  "msg": "OK",
  "request_id": "c3d4e5f6g7h8i9j0a1b2"
}

获取最上层组件信息

URL: /activity/top_activity
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "ta123456"
}

获取最近任务列表

URL: /activity/recent_tasks
方式: GET
参数:
参数名类型必选说明
max_num int 否最大数量，默认 20

参数名	类型	必选	说明
max_num	int	否	最大数量，默认 20

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings",
      "num_activities": 1,
      "last_active_time": 1736412345000
    }
  ],
  "msg": "OK",
  "request_id": "rt123456"
}

清空任务栈

移除所有最近任务（类似于清理后台最近应用卡片）。

URL: /activity/clear_tasks
方式: POST

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings"
    }
  ],
  "msg": "OK",
  "request_id": "ct123456"
}

切换任务到前台

URL: /activity/move_to_front
方式: POST
参数:
参数名类型必选说明
task_id int 是任务 ID
请求示例:
json
```
{
  "task_id": 123
}
```

参数名	类型	必选	说明
task_id	int	是	任务 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "mtf123456"
}

应用管理 (Package)

安装应用

支持标准 APK 以及 APKS、APKM、XAPK 等分包格式。异步安装会立即返回任务 ID，同步安装会阻塞直至安装完成。

URL: /package/install (异步) / /package/install_sync (同步)
方式: POST
Content-Type: multipart/form-data 或 application/json
参数:
参数名类型必选说明
file file 否 APK/XAPK 文件 (Multipart 方式)
file_path string 否 APK/XAPK 实例内路径 (JSON 方式)
installer_package_name string 否指定安装来源包名

参数名	类型	必选	说明
file	file	否	APK/XAPK 文件 (Multipart 方式)
file_path	string	否	APK/XAPK 实例内路径 (JSON 方式)
installer_package_name	string	否	指定安装来源包名

返回示例 (异步):

json

{
  "code": 200,
  "data": "m3n4o5p6q7r8s9t0u1v2",
  "msg": "OK",
  "request_id": "m3n4o5p6q7r8s9t0u1v2"
}

返回示例 (同步):

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "message": "Success"
  },
  "msg": "OK",
  "request_id": "ins_sync_123"
}

卸载应用

URL: /package/uninstall
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "n4o5p6q7r8s9t0u1v2w3"
}

设置应用启用状态

URL: /package/enabled
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名
enabled boolean 是是否启用

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "se123456"
}

获取已安装应用列表

URL: /package/list
方式: GET
参数:
参数名类型必选说明
type string 否 all=全部, system=系统应用, user=用户应用 (默认 user)

参数名	类型	必选	说明
type	string	否	`all`=全部, `system`=系统应用, `user`=用户应用 (默认 `user`)

返回示例:

json

{
  "code": 200,
  "data": {
    "type": "user",
    "count": 1,
    "packages": [
      {
        "package_name": "com.example.app",
        "app_name": "示例应用",
        "version_name": "1.0.0",
        "version_code": 1,
        "is_system": false,
        "enabled": true,
        "uid": 10123,
        "source_dir": "/data/app/...",
        "data_dir": "/data/user/0/..."
      }
    ]
  },
  "msg": "OK",
  "request_id": "l2m3n4o5p6q7r8s9t0u1"
}

导出应用 APK

如果应用是单一 APK，将返回原始 APK 二进制流。如果应用是分包（Split APKs），将自动打包成 ZIP 格式并返回二进制流。

URL: /package/export
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名
返回: APK 或 ZIP 二进制流。

清除应用数据

URL: /package/clear_data
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

请求示例:

json

{
  "package_name": "com.android.settings"
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "b2c3d4e5f6g7h8i9j0a1"
}

输入控制 (Input)

点击

URL: /input/click
方式: POST
参数:
参数名类型必选说明
x int 是 X 坐标
y int 是 Y 坐标
请求示例:
json
```
{
  "x": 100,
  "y": 200
}
```

参数名	类型	必选	说明
x	int	是	X 坐标
y	int	是	Y 坐标

返回示例:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200
  },
  "msg": "OK",
  "request_id": "d4e5f6g7h8i9j0a1b2c3"
}

多击

URL: /input/multi_click
方式: POST
参数:
参数名类型必选说明
x int 是 X 坐标
y int 是 Y 坐标
times int 否点击次数，默认 2
interval long 否点击间隔 (ms)，默认 100

参数名	类型	必选	说明
x	int	是	X 坐标
y	int	是	Y 坐标
times	int	否	点击次数，默认 2
interval	long	否	点击间隔 (ms)，默认 100

请求示例:

json

{
  "x": 100,
  "y": 200,
  "times": 3,
  "interval": 200
}

返回示例:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200,
    "times": 3,
    "interval": 200
  },
  "msg": "OK",
  "request_id": "mc12345678"
}

输入文本

URL: /input/text
方式: POST
参数:
参数名类型必选说明
text string 是要输入的文本内容
请求示例:
json
```
{
  "text": "Hello World"
}
```

参数名	类型	必选	说明
text	string	是	要输入的文本内容

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "e5f6g7h8i9j0a1b2c3d4"
}

按键

URL: /input/keyevent
方式: POST
参数:
参数名类型必选说明
key_code int 否单个按键 KeyCode (如 4=返回, 3=Home)
key_codes array 否组合按键列表 (如 [113, 29] 为 CTRL + A)
请求示例 (单按键):
json
```
{
  "key_code": 4
}
```

参数名	类型	必选	说明
key_code	int	否	单个按键 KeyCode (如 4=返回, 3=Home)
key_codes	array	否	组合按键列表 (如 [113, 29] 为 CTRL + A)

返回示例:

json

{
  "code": 200,
  "data": [4],
  "msg": "OK",
  "request_id": "f6g7h8i9j0a1b2c3d4e5"
}

滑动

URL: /input/swipe
方式: POST

参数:

参数名	类型	必选	说明
start_x	int	是	起点 X
start_y	int	是	起点 Y
end_x	int	是	终点 X
end_y	int	是	终点 Y
duration	int	否	持续时间 (ms)，默认 300
up_delay	long	否	松手延迟 (ms)，null 为立即松手，-1 为不松手

请求示例:

json

{
  "start_x": 100,
  "start_y": 800,
  "end_x": 100,
  "end_y": 200,
  "duration": 500
}

返回示例:

json

{
  "code": 200,
  "data": {
    "start_x": 100,
    "start_y": 800,
    "end_x": 100,
    "end_y": 200,
    "duration": 500,
    "up_delay": null
  },
  "msg": "OK",
  "request_id": "g7h8i9j0a1b2c3d4e5f6"
}

曲线滑动

URL: /input/scroll_bezier
方式: POST

参数:

参数名	类型	必选	说明
start_x	int	是	起点 X
start_y	int	是	起点 Y
end_x	int	是	终点 X
end_y	int	是	终点 Y
duration	int	否	持续时间 (ms)，默认 500
up_delay	long	否	松手延迟 (ms)，null 为立即松手，-1 为不松手
clear_fling	string	否	惯性消除策略: "repeat_last"=重复最后一个点消除惯性

请求示例:

json

{
  "start_x": 200,
  "start_y": 1600,
  "end_x": 200,
  "end_y": 200,
  "duration": 500
}

返回示例:

json

{
  "code": 200,
  "data": {
    "start_x": 200,
    "start_y": 1600,
    "end_x": 200,
    "end_y": 200,
    "duration": 500
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

发送原始 MotionEvent 事件

URL: /input/motion_event
方式: POST
参数:
参数名类型必选说明
events array 是 MotionEvent 事件列表，详见下方说明

参数名	类型	必选	说明
events	array	是	MotionEvent 事件列表，详见下方说明

Event 对象说明:

参数名	类型	必选	说明
action	int	是	动作类型: 0=DOWN, 1=UP, 2=MOVE, 3=CANCEL...
x	float	是	X 坐标
y	float	是	Y 坐标
delay	long	否	发送此事件前的延迟 (ms)
pressure	float	否	压力值 (默认 1.0)
down_time	long	否	按下时间戳 (默认使用首个事件时间)

请求示例:

json

{
  "events": [
    { "action": 0, "x": 100, "y": 200, "delay": 0 },
    { "action": 2, "x": 150, "y": 250, "delay": 50 },
    { "action": 1, "x": 200, "y": 300, "delay": 50 }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": {
    "sent_count": 3,
    "events": [ ... ]
  },
  "msg": "OK",
  "request_id": "mot1234567890"
}

权限管理 (Permission)

获取应用权限

URL: /permission/get
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 2,
    "permissions": [
      { "permission": "android.permission.CAMERA", "granted": true },
      { "permission": "android.permission.RECORD_AUDIO", "granted": false }
    ]
  },
  "msg": "OK",
  "request_id": "per1234567890"
}

设置应用权限

URL: /permission/set
方式: POST

参数:

参数名	类型	必选	说明
package_name	string	是	应用包名
grant	boolean	是	true=授予, false=撤销
permissions	array	否	权限列表 (如 ["android.permission.CAMERA"])
grant_all	boolean	否	是否授予所有请求的权限
special_permission	boolean	否	是否授予特殊系统权限（包含悬浮窗、文件管理、录屏等）

特殊权限说明: 当 special_permission 为 true 时，将自动授予应用以下特殊权限：
- 悬浮窗: 允许应用在其他应用上层显示。
- 文件管理: 允许应用访问所有外部存储文件（Android 11+）。
- 录屏: 自动允许录屏请求，跳过系统安全确认。

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "grant": true,
    "success_count": 1
  },
  "msg": "OK",
  "request_id": "per0987654321"
}

文件管理 (File)

导入文件

URL: /file/import
方式: POST
Content-Type: multipart/form-data
参数:
参数名类型必选说明
dir_path string 是目标目录 (如 /sdcard/Download/)
file file 是文件字段，支持多个文件

参数名	类型	必选	说明
dir_path	string	是	目标目录 (如 `/sdcard/Download/`)
file	file	是	文件字段，支持多个文件

返回示例:

json

{
  "code": 200,
  "data": {
    "files": [
      {
        "file_path": "/sdcard/Download/test.apk",
        "file_size": 123456
      }
    ]
  },
  "msg": "OK",
  "request_id": "t0u1v2w3x4y5z6a7b8c9"
}

导出文件

URL: /file/export
方式: GET
参数:
参数名类型必选说明
path string 是文件路径
返回: 文件二进制流。

参数名	类型	必选	说明
path	string	是	文件路径

列出目录内容

URL: /file/list
方式: GET
参数:
参数名类型必选说明
path string 是目录路径
show_hidden boolean 否是否显示隐藏文件 (默认 false)
请求示例:
json
```
{
  "path": "/sdcard"
}
```

参数名	类型	必选	说明
path	string	是	目录路径
show_hidden	boolean	否	是否显示隐藏文件 (默认 false)

返回示例:

json

{
  "code": 200,
  "data": {
    "path": "/sdcard",
    "count": 2,
    "files": [
      {
        "name": "Download",
        "absolute_path": "/sdcard/Download",
        "is_directory": true,
        "is_file": false,
        "size": 4096,
        "last_modified": 1736412345000,
        "can_read": true,
        "can_write": true,
        "can_execute": true
      }
    ]
  },
  "msg": "OK",
  "request_id": "u1v2w3x4y5z6a7b8c9d0"
}

系统设置 (System)

执行 Shell 命令

URL: /system/shell
方式: POST
参数:
参数名类型必选说明
command string 是要执行的 Shell 命令
is_root boolean 否是否以 root 用户执行 (默认 true)

参数名	类型	必选	说明
command	string	是	要执行的 Shell 命令
is_root	boolean	否	是否以 root 用户执行 (默认 true)

请求示例:

json

{
  "command": "ls -l /sdcard",
  "is_root": true
}

返回示例:

json

{
  "code": 200,
  "data": {
    "command": "ls -l /sdcard",
    "is_root": true,
    "exit_code": 0,
    "output": "total 0\ndrwxrwx--- 2 root ...",
    "error": ""
  },
  "msg": "OK",
  "request_id": "q7r8s9t0u1v2w3x4y5z6"
}

设置壁纸

URL: /system/wallpaper
方式: POST
参数:
参数名类型必选说明
path string 是图片路径 (实例内路径或 Assets 路径)
type string 否 file (默认) 或 asset

参数名	类型	必选	说明
path	string	是	图片路径 (实例内路径或 Assets 路径)
type	string	否	`file` (默认) 或 `asset`

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "wal1234567890"
}

电源管理 (Power)

点亮 / 熄灭屏幕

URL: /power/set_screen
方式: POST
参数:
参数名类型必选说明
on boolean 是 true 为点亮屏幕, false 为熄灭屏幕
请求示例:
json
```
{
  "on": true
}
```

参数名	类型	必选	说明
on	boolean	是	`true` 为点亮屏幕, `false` 为熄灭屏幕

返回示例:

json

{
  "code": 200,
  "data": {
    "on": true
  },
  "msg": "OK",
  "request_id": "ps123456"
}

锁定 / 解锁屏幕

URL: /power/locked
方式: POST
参数:
参数名类型必选说明
locked boolean 是 true 为锁定屏幕, false 为解锁屏幕
请求示例:
json
```
{
  "locked": true
}
```

参数名	类型	必选	说明
locked	boolean	是	`true` 为锁定屏幕, `false` 为解锁屏幕

返回示例:

json

{
  "code": 200,
  "data": {
    "locked": true
  },
  "msg": "OK",
  "request_id": "pl123456"
}

获取屏幕与锁屏状态

URL: /power/status
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "is_screen_on": true,
    "is_locked": false
  },
  "msg": "OK",
  "request_id": "pst123456"
}

本地化 (Locale)

获取本地化信息

获取系统支持的所有语言、国家/地区以及时区列表。

URL: /locale/list
方式: GET
参数:
参数名类型必选说明
display_languages array 否指定显示名称的语言代码列表，默认 ["zh", "en"]

参数名	类型	必选	说明
display_languages	array	否	指定显示名称的语言代码列表，默认 `["zh", "en"]`

返回示例:

json

{
  "code": 200,
  "data": {
    "languages": [
      { 
        "code": "zh", 
        "names": { "zh": "中文", "en": "Chinese" } 
      },
      { 
        "code": "en", 
        "names": { "zh": "英语", "en": "English" } 
      }
    ],
    "regions": [
      { 
        "code": "CN", 
        "names": { "zh": "中国", "en": "China" } 
      },
      { 
        "code": "US", 
        "names": { "zh": "美国", "en": "United States" } 
      }
    ],
    "time_zones": [
      {
        "id": "Asia/Shanghai",
        "names": { "zh": "中国标准时间 (上海)", "en": "China Standard Time (Shanghai)" },
        "offset": 28800000,
        "raw_offset": 28800000
      }
    ]
  },
  "msg": "OK",
  "request_id": "li123456"
}

剪贴板 (Clipboard)

设置剪贴板

URL: /clipboard/set
方式: POST
参数:
参数名类型必选说明
text string 是文本内容
请求示例:
json
```
{
  "text": "Hello World"
}
```

参数名	类型	必选	说明
text	string	是	文本内容

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "h8i9j0a1b2c3d4e5f6g7"
}

获取当前剪贴板

URL: /clipboard/get
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "i9j0a1b2c3d4e5f6g7h8"
}

获取剪贴板历史列表

URL: /clipboard/list
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 2,
    "mime_type": "text/plain",
    "items": ["Hello", "World"]
  },
  "msg": "OK",
  "request_id": "j0a1b2c3d4e5f6g7h8i9"
}

清空剪贴板

URL: /clipboard/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "k1l2m3n4o5p6q7r8s9t0"
}

屏幕与显示 (Display)

获取屏幕信息

URL: /display/info
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "width": 1080,
    "height": 1920,
    "rotation": 0,
    "orientation": 1
  },
  "msg": "OK",
  "request_id": "o5p6q7r8s9t0u1v2w3x4"
}

屏幕旋转

URL: /display/rotate
方式: POST
参数:
参数名类型必选说明
rotation int 是旋转角度：0=0°, 1=90°, 2=180°, 3=270°
请求示例:
json
```
{
  "rotation": 1
}
```

参数名	类型	必选	说明
rotation	int	是	旋转角度：0=0°, 1=90°, 2=180°, 3=270°

返回示例:

json

{
  "code": 200,
  "data": {
    "width": 1920,
    "height": 1080,
    "rotation": 1,
    "orientation": 0
  },
  "msg": "OK",
  "request_id": "p6q7r8s9t0u1v2w3x4y5"
}

屏幕截图（压缩）

URL: /screenshot/format
方式: GET
参数:
参数名类型必选说明
format string 否 webp, png, jpeg (默认 jpg)
quality int 否质量 (1-100)，默认 100
返回: 原始图片二进制流 (Content-Type: image/jpeg 等)。

参数名	类型	必选	说明
format	string	否	`webp`, `png`, `jpeg` (默认 `jpg`)
quality	int	否	质量 (1-100)，默认 100

获取截图

URL: /screenshot/raw
方式: GET
返回: 原始 RGBA 像素数据流 (ARGB_8888)。每个像素占 4 字节。

联系人管理 (Contact)

添加联系人

URL: /contact/add
方式: POST
参数:
参数名类型必选说明
name string 是姓名
phone string 是电话号码
email string 否邮箱
organization string 否公司/组织
note string 否备注

参数名	类型	必选	说明
name	string	是	姓名
phone	string	是	电话号码
email	string	否	邮箱
organization	string	否	公司/组织
note	string	否	备注

请求示例:

json

{
  "name": "张三",
  "phone": "13800138000"
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "con1234567890"
}

删除联系人

URL: /contact/delete
方式: POST
参数:
参数名类型必选说明
id long 是联系人 ID
请求示例:
json
```
{
  "id": 1
}
```

参数名	类型	必选	说明
id	long	是	联系人 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cd123456"
}

获取联系人列表

URL: /contact/list
方式: GET
参数:
参数名类型必选说明
offset int 否偏移量，默认 0
limit int 否限制数量，默认 100

参数名	类型	必选	说明
offset	int	否	偏移量，默认 0
limit	int	否	限制数量，默认 100

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "contacts": [
      { "id": 1, "name": "张三", "phones": ["13800138000"] }
    ]
  },
  "msg": "OK",
  "request_id": "cl123456"
}

短信管理 (SMS)

获取短信列表

URL: /sms/list
方式: GET
参数:
参数名类型必选说明
offset int 否偏移量，默认 0
limit int 否限制数量，默认 100

参数名	类型	必选	说明
offset	int	否	偏移量，默认 0
limit	int	否	限制数量，默认 100

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "sms_list": [
      { "id": 1, "address": "10086", "body": "余额不足", "date": 1736412345000, "type": 1, "read": 1 }
    ]
  },
  "msg": "OK",
  "request_id": "sl123456"
}

添加短信

URL: /sms/add
方式: POST
参数:
参数名类型必选说明
address string 是对方号码
body string 是短信内容
type int 否类型：1=接收, 2=发送 (默认 1)
date long 否时间戳，默认当前时间

参数名	类型	必选	说明
address	string	是	对方号码
body	string	是	短信内容
type	int	否	类型：1=接收, 2=发送 (默认 1)
date	long	否	时间戳，默认当前时间

请求示例:

json

{
  "address": "10086",
  "body": "您的余额不足，请及时充值。",
  "type": 1
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sa123456"
}

删除短信

URL: /sms/delete
方式: POST
参数:
参数名类型必选说明
id long 是短信 ID

参数名	类型	必选	说明
id	long	是	短信 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sd123456"
}

账号管理 (Account)

添加账号

URL: /account/add
方式: POST
参数:
参数名类型必选说明
name string 是账号名 (如 example@gmail.com)
type string 是账号类型 (如 com.google)
password string 否密码
user_data object 否用户自定义数据 (Key-Value)

参数名	类型	必选	说明
name	string	是	账号名 (如 `example@gmail.com`)
type	string	是	账号类型 (如 `com.google`)
password	string	否	密码
user_data	object	否	用户自定义数据 (Key-Value)

请求示例:

json

{
  "name": "test_user",
  "type": "com.example.account",
  "password": "password123",
  "user_data": {
    "key1": "value1"
  }
}

返回示例:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "aa123456"
}

获取账号列表

URL: /account/list
方式: GET
参数:
参数名类型必选说明
type string 否过滤账号类型

参数名	类型	必选	说明
type	string	否	过滤账号类型

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "accounts": [
      { "name": "test_user", "type": "com.example.account" }
    ]
  },
  "msg": "OK",
  "request_id": "al123456"
}

删除账号

URL: /account/delete
方式: POST
参数:
参数名类型必选说明
name string 是账号名
type string 是账号类型

参数名	类型	必选	说明
name	string	是	账号名
type	string	是	账号类型

返回示例:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "ad123456"
}

多媒体与音频 (Media)

设置音量

URL: /media/set_volume
方式: POST

参数:

参数名	类型	必选	说明
stream_type	string	是	音量类型：`music`=媒体, `voice_call`=通话, `ring`=铃声, `alarm`=闹钟, `notification`=通知
volume	int	是	音量值 (0 到最大值)
show_ui	boolean	否	是否显示系统音量 UI (默认 `true`)

请求示例:

json

{
  "stream_type": "music",
  "volume": 8
}

返回示例:

json

{
  "code": 200,
  "data": {
    "stream_type": "music",
    "volume": 8
  },
  "msg": "OK",
  "request_id": "sv123456"
}

静音 / 取消静音

URL: /media/mute
方式: POST
参数:
参数名类型必选说明
mute boolean 是 true 为静音，false 为取消静音

参数名	类型	必选	说明
mute	boolean	是	`true` 为静音，`false` 为取消静音

返回示例:

json

{
  "code": 200,
  "data": {
    "mute": true
  },
  "msg": "OK",
  "request_id": "mu123456"
}

获取音量信息

URL: /media/get_volume
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "music": { "current": 8, "max": 15 },
    "voice_call": { "current": 5, "max": 10 },
    "ring": { "current": 10, "max": 15 },
    "is_mute": false
  },
  "msg": "OK",
  "request_id": "vi123456"
}

无障碍 (Accessibility)

导出 UI 层次结构

URL: /accessibility/dump
方式: GET

返回示例:

json

{
  "code": 200,
  "data": "<?xml version='1.0' encoding='UTF-8' standalone='yes' ?><hierarchy ...",
  "msg": "OK",
  "request_id": "r8s9t0u1v2w3x4y5z6a7"
}

查找 UI 节点

根据指定条件查找当前屏幕上的 UI 节点。需要镜像版本 20260113 及以上支持。

URL: /accessibility/find_node
方式: POST

参数:

参数名	类型	必选	说明
xpath	string	否	XPath 表达式，优先级最高
text	string	否	节点文本。支持正则表达式匹配（如 `.设置.`）
content_desc	string	否	节点内容描述。支持正则表达式
name	string	否	节点文本或内容描述。支持正则表达式
class	string	否	节点类名 (class)
resource_id	string	否	节点资源 ID (resource-id)
package	string	否	应用包名
index	int	否	节点在其父节点中的索引
clickable	boolean	否	是否可点击
enabled	boolean	否	是否启用
scrollable	boolean	否	是否可滚动
focusable	boolean	否	是否可聚焦
focused	boolean	否	是否已聚焦
selected	boolean	否	是否已选中
checkable	boolean	否	是否可勾选
checked	boolean	否	是否已勾选
center_x	int	否	节点中心 X 坐标
center_y	int	否	节点中心 Y 坐标

请求示例 (组合条件 + 正则):

json

{
  "text": ".*设置.*",
  "class": "android.widget.TextView",
  "clickable": true
}

请求示例 (精准匹配):

json

{
  "text": "设置",
  "class": "android.widget.TextView",
  "resource_id": "com.android.settings:id/title"
}

请求示例 (XPath):

json

{
  "xpath": "//node[@text='设置' and @clickable='true']"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "nodes": [
      {
        "text": "设置",
        "class": "android.widget.TextView",
        "package": "com.android.settings",
        "content_desc": "设置按钮",
        "resource_id": "com.android.settings:id/title",
        "bounds": { "left": 100, "top": 200, "right": 300, "bottom": 400 },
        "center_x": 200,
        "center_y": 300,
        "clickable": true,
        "enabled": true,
        "focusable": true,
        "focused": false,
        "scrollable": false,
        "long_clickable": false,
        "password": false,
        "selected": false
      }
    ]
  },
  "msg": "OK",
  "request_id": "fn123456"
}

执行节点动作

URL: /accessibility/perform_action
方式: POST
参数:
参数名类型必选说明
text string 否节点文本
view_id string 否节点 Resource ID
action int 是动作码 (16=点击, 32=长按等)

参数名	类型	必选	说明
text	string	否	节点文本
view_id	string	否	节点 Resource ID
action	int	是	动作码 (16=点击, 32=长按等)

返回示例:

json

{
  "code": 200,
  "data": {
    "performed_count": 1
  },
  "msg": "OK",
  "request_id": "pa123456"
}

设置无障碍服务隐藏状态

设置指定应用是否在无障碍服务列表中隐藏。需要镜像版本 20260113 及以上支持。

URL: /accessibility/set_hidden
方式: POST
参数:
参数名类型必选说明
package_names array 是无障碍服务包名数组
hidden boolean 否是否隐藏，默认 true

参数名	类型	必选	说明
package_names	array	是	无障碍服务包名数组
hidden	boolean	否	是否隐藏，默认 `true`

返回示例:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "sh123456"
}

获取无障碍服务隐藏状态

获取当前处于隐藏状态的无障碍服务包名列表。需要镜像版本 20260113 及以上支持。

URL: /accessibility/get_hidden
方式: GET

返回示例:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "gh123456"
}

通知管理 (Notification)

获取活跃通知列表

URL: /notification/list
方式: GET
参数:
参数名类型必选说明
package_name string 否过滤指定应用的通知

参数名	类型	必选	说明
package_name	string	否	过滤指定应用的通知

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "notifications": [
      {
        "package_name": "com.android.settings",
        "id": 1,
        "key": "0|com.android.settings|1|null|1000",
        "title": "通知标题",
        "text": "通知内容",
        "post_time": 1736412345000,
        "is_ongoing": false,
        "is_clearable": true,
        "priority": 0
      }
    ]
  },
  "msg": "OK",
  "request_id": "v2w3x4y5z6a7b8c9d0e1"
}

获取应用通知渠道列表

URL: /notification/channels
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 1,
    "channels": [
      {
        "id": "channel_id",
        "name": "渠道名称",
        "importance": 3,
        "description": "渠道描述"
      }
    ]
  },
  "msg": "OK",
  "request_id": "nc123456"
}

设备信息 (Device)

随机机型信息

随机生成并设置云机的机型信息。注意：该接口仅支持虚拟机类型云机。

URL: /device/random_model
方式: POST
参数:
参数名类型必选说明
is_china boolean 否是否仅随机中国机型，默认 false

返回示例:

json

{
  "code": 200,
  "data": {
    "manufacturer": "Xiaomi",
    "model": "MI 11",
    "brand": "Xiaomi",
    "device": "cetus",
    "product": "cetus",
    "hardware": "qcom"
  },
  "msg": "OK",
  "request_id": "s9t0u1v2w3x4y5z6a7b8"
}

Google 服务 (Google)

启用/禁用谷歌套件

启用或禁用完整的谷歌服务套件（包含 GMS 核心、Play 商店、服务框架等）。

URL: /google/set_enabled
方式: POST
参数:
参数名类型必选说明
enabled boolean 是 true 为启用, false 为禁用

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gs123456"
}

重置 GAID

重置 Google 广告 ID (GAID)。

URL: /google/reset_gaid
方式: POST
参数:
参数名类型必选说明
gaid string 否指定 GAID，不传则随机生成

返回示例:

json

{
  "code": 200,
  "data": "550e8400-e29b-41d4-a716-446655440000",
  "msg": "OK",
  "request_id": "gr123456"
}

获取谷歌套件启用状态

获取当前谷歌服务套件的启用状态。只有套件内所有组件均处于启用状态，返回 true。

URL: /google/get_enabled
方式: GET

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gst123456"
}

Android Control API 接口文档 ​

简介 ​

调用方式 ​

1. 云机外HTTP调用 ​

2. 云机内HTTP调用 ​

3. Socket 调用 ​

4. 命令行 (CLI) 调用 ​

通用响应结构 ​

逻辑处理 (Logic) ​

暂停响应 ​

工作流 (Workflow) ​

执行工作流 ​

应用运行管理 (Activity) ​

启动应用 ​

启动指定 Activity ​

停止应用 ​

获取正在运行的进程 ​

获取最上层组件信息 ​

获取最近任务列表 ​

清空任务栈 ​

切换任务到前台 ​

应用管理 (Package) ​

安装应用 ​

卸载应用 ​

设置应用启用状态 ​

获取已安装应用列表 ​

导出应用 APK ​

清除应用数据 ​

输入控制 (Input) ​

点击 ​

多击 ​

输入文本 ​

按键 ​

滑动 ​

曲线滑动 ​

发送原始 MotionEvent 事件 ​

权限管理 (Permission) ​

获取应用权限 ​

设置应用权限 ​

文件管理 (File) ​

导入文件 ​

导出文件 ​

列出目录内容 ​

系统设置 (System) ​

执行 Shell 命令 ​

设置壁纸 ​

电源管理 (Power) ​

点亮 / 熄灭屏幕 ​

锁定 / 解锁屏幕 ​

获取屏幕与锁屏状态 ​

本地化 (Locale) ​

获取本地化信息 ​

剪贴板 (Clipboard) ​

设置剪贴板 ​

获取当前剪贴板 ​

获取剪贴板历史列表 ​

清空剪贴板 ​

屏幕与显示 (Display) ​

获取屏幕信息 ​

屏幕旋转 ​

屏幕截图（压缩） ​

获取截图 ​

联系人管理 (Contact) ​

添加联系人 ​

删除联系人 ​

获取联系人列表 ​

短信管理 (SMS) ​

获取短信列表 ​

添加短信 ​

删除短信 ​

账号管理 (Account) ​

添加账号 ​

获取账号列表 ​

删除账号 ​

多媒体与音频 (Media) ​

设置音量 ​

静音 / 取消静音 ​

获取音量信息 ​

无障碍 (Accessibility) ​

导出 UI 层次结构 ​

Android Control API 接口文档

简介

调用方式

1. 云机外HTTP调用

2. 云机内HTTP调用

3. Socket 调用

4. 命令行 (CLI) 调用

通用响应结构

逻辑处理 (Logic)

暂停响应

工作流 (Workflow)

执行工作流

应用运行管理 (Activity)

启动应用

启动指定 Activity

停止应用

获取正在运行的进程

获取最上层组件信息

获取最近任务列表

清空任务栈

切换任务到前台

应用管理 (Package)

安装应用

卸载应用

设置应用启用状态

获取已安装应用列表

导出应用 APK

清除应用数据

输入控制 (Input)

点击

多击

输入文本

按键

滑动

曲线滑动

发送原始 MotionEvent 事件

权限管理 (Permission)

获取应用权限

设置应用权限

文件管理 (File)

导入文件

导出文件

列出目录内容

系统设置 (System)

执行 Shell 命令

设置壁纸

电源管理 (Power)

点亮 / 熄灭屏幕

锁定 / 解锁屏幕

获取屏幕与锁屏状态

本地化 (Locale)

获取本地化信息

剪贴板 (Clipboard)

设置剪贴板

获取当前剪贴板

获取剪贴板历史列表

清空剪贴板

屏幕与显示 (Display)

获取屏幕信息

屏幕旋转

屏幕截图（压缩）

获取截图

联系人管理 (Contact)

添加联系人

删除联系人

获取联系人列表

短信管理 (SMS)

获取短信列表

添加短信

删除短信

账号管理 (Account)

添加账号

获取账号列表

删除账号

多媒体与音频 (Media)

设置音量

静音 / 取消静音

获取音量信息

无障碍 (Accessibility)

导出 UI 层次结构