Android Control API 接口文档

更新时间: 2026年1月9日

::: warning 支持版本提示 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 格式，统一响应结构如下：

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

逻辑处理 (Logic)

暂停响应

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

URL: /logic/sleep
方式: POST
参数:

参数名类型必选说明

duration long 是暂停时长 (ms)

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

返回示例:

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

工作流 (Workflow)

执行工作流

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

URL: /workflow
方式: POST
参数:

参数名类型必选说明

actions array 是动作列表。每个对象包含 path (接口路径) 和 params (参数对象)

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

请求示例:

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

返回示例:

{
  "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 是应用包名

请求示例:

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

返回示例:

{
  "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 键值对)

请求示例:

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

返回示例:

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

停止应用

URL: /activity/stop
方式: POST
参数:

参数名类型必选说明

package_name string 是应用包名

请求示例:

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

返回示例:

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

获取正在运行的进程

URL: /activity/processes
方式: GET

返回示例:

{
  "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

返回示例:

{
  "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

返回示例:

{
  "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

返回示例:

{
  "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
请求示例:
```
{
  "task_id": 123
}
```

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

返回示例:

{
  "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	否	指定安装来源包名

返回示例 (异步):

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

返回示例 (同步):

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

卸载应用

URL: /package/uninstall
方式: POST
参数:

参数名类型必选说明

package_name string 是应用包名

返回示例:

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

设置应用启用状态

URL: /package/enabled
方式: POST
参数:

参数名类型必选说明

package_name string 是应用包名

enabled boolean 是是否启用

返回示例:

{
  "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`)

返回示例:

{
  "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 是应用包名

请求示例:

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

返回示例:

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

输入控制 (Input)

点击

URL: /input/click
方式: POST
参数:

参数名类型必选说明

x int 是 X 坐标

y int 是 Y 坐标
请求示例:
```
{
  "x": 100,
  "y": 200
}
```

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

返回示例:

{
  "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

请求示例:

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

返回示例:

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

输入文本

URL: /input/text
方式: POST
参数:

参数名类型必选说明

text string 是要输入的文本内容
请求示例:
```
{
  "text": "Hello World"
}
```

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

返回示例:

{
  "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)
请求示例 (单按键):
```
{
  "key_code": 4
}
```

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

返回示例:

{
  "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 为不松手

请求示例:

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

返回示例:

{
  "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"=重复最后一个点消除惯性

请求示例:

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

返回示例:

{
  "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	否	按下时间戳 (默认使用首个事件时间)

请求示例:

{
  "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 }
  ]
}

返回示例:

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

权限管理 (Permission)

获取应用权限

URL: /permission/get
方式: GET
参数:

参数名类型必选说明

package_name string 是应用包名

返回示例:

{
  "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+）。
- 录屏: 自动允许录屏请求，跳过系统安全确认。

返回示例:

{
  "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	是	文件字段，支持多个文件

返回示例:

{
  "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)
请求示例:
```
{
  "path": "/sdcard"
}
```

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

返回示例:

{
  "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)

请求示例:

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

返回示例:

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

返回示例:

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

电源管理 (Power)

点亮 / 熄灭屏幕

URL: /power/set_screen
方式: POST
参数:

参数名类型必选说明

on boolean 是 true 为点亮屏幕, false 为熄灭屏幕
请求示例:
```
{
  "on": true
}
```

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

返回示例:

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

锁定 / 解锁屏幕

URL: /power/locked
方式: POST
参数:

参数名类型必选说明

locked boolean 是 true 为锁定屏幕, false 为解锁屏幕
请求示例:
```
{
  "locked": true
}
```

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

返回示例:

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

获取屏幕与锁屏状态

URL: /power/status
方式: GET

返回示例:

{
  "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"]`

返回示例:

{
  "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 是文本内容
请求示例:
```
{
  "text": "Hello World"
}
```

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

返回示例:

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

获取当前剪贴板

URL: /clipboard/get
方式: GET

返回示例:

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

获取剪贴板历史列表

URL: /clipboard/list
方式: GET

返回示例:

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

清空剪贴板

URL: /clipboard/clear
方式: POST

返回示例:

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

屏幕与显示 (Display)

获取屏幕信息

URL: /display/info
方式: GET

返回示例:

{
  "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°
请求示例:
```
{
  "rotation": 1
}
```

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

返回示例:

{
  "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	否	备注

请求示例:

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

返回示例:

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

删除联系人

URL: /contact/delete
方式: POST
参数:

参数名类型必选说明

id long 是联系人 ID
请求示例:
```
{
  "id": 1
}
```

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

返回示例:

{
  "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

返回示例:

{
  "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

返回示例:

{
  "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": "10086",
  "body": "您的余额不足，请及时充值。",
  "type": 1
}

返回示例:

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

删除短信

URL: /sms/delete
方式: POST
参数:

参数名类型必选说明

id long 是短信 ID

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

返回示例:

{
  "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": "test_user",
  "type": "com.example.account",
  "password": "password123",
  "user_data": {
    "key1": "value1"
  }
}

返回示例:

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

获取账号列表

URL: /account/list
方式: GET
参数:

参数名类型必选说明

type string 否过滤账号类型

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

返回示例:

{
  "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	是	账号类型

返回示例:

{
  "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`)

请求示例:

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

返回示例:

{
  "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` 为取消静音

返回示例:

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

获取音量信息

URL: /media/get_volume
方式: GET

返回示例:

{
  "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

返回示例:

{
  "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 坐标

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

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

请求示例 (精准匹配):

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

请求示例 (XPath):

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

返回示例:

{
  "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=长按等)

返回示例:

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

返回示例:

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

获取无障碍服务隐藏状态

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

URL: /accessibility/get_hidden
方式: GET

返回示例:

{
  "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	否	过滤指定应用的通知

返回示例:

{
  "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 是应用包名

返回示例:

{
  "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

返回示例:

{
  "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 为禁用

返回示例:

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

重置 GAID

重置 Google 广告 ID (GAID)。

URL: /google/reset_gaid
方式: POST
参数:

参数名类型必选说明

gaid string 否指定 GAID，不传则随机生成

返回示例:

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

获取谷歌套件启用状态

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

URL: /google/get_enabled
方式: GET

返回示例:

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