Android Control API 接口文档

更新时间: 2026年2月11日

支持版本提示

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}/{接口路径}

以「获取已安装应用列表」为例：

bash

curl http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list

javascript

const resp = await fetch(
  "http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list"
);
console.log(await resp.json());

python

import requests

resp = requests.get("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
print(resp.json())

java

HttpURLConnection conn = (HttpURLConnection)
    new URL("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
        .openConnection();
conn.setRequestMethod("GET");
String body = new String(conn.getInputStream().readAllBytes());
System.out.println(body);

resp, _ := http.Get("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

2. 云机内 HTTP 调用

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

URL 格式: http://127.0.0.1:18185/api/{接口路径}

以「获取已安装应用列表」为例：

bash

curl http://127.0.0.1:18185/api/package/list

javascript

const resp = await fetch("http://127.0.0.1:18185/api/package/list");
console.log(await resp.json());

python

import requests

resp = requests.get("http://127.0.0.1:18185/api/package/list")
print(resp.json())

kotlin

val url = URL("http://127.0.0.1:18185/api/package/list")
val conn = url.openConnection() as HttpURLConnection
val body = conn.inputStream.bufferedReader().readText()
println(body)

java

HttpURLConnection conn = (HttpURLConnection)
    new URL("http://127.0.0.1:18185/api/package/list").openConnection();
String body = new String(conn.getInputStream().readAllBytes());
System.out.println(body);

3. TCP 调用

在云机内或宿主机通过 TCP 进行低延迟调用：

地址: 127.0.0.1:18186
协议: 4字节大端长度头 + JSON Payload

请求 JSON 格式：{"path": "接口路径", "params": {参数}}

以「获取已安装应用列表」为例：

javascript

const net = require("net");

function tcpCall(path, params = {}, host = "127.0.0.1", port = 18186) {
  return new Promise((resolve, reject) => {
    const client = net.createConnection({ host, port }, () => {
      const payload = Buffer.from(JSON.stringify({ path, params }));
      const header = Buffer.alloc(4);
      header.writeUInt32BE(payload.length);
      client.write(Buffer.concat([header, payload]));
    });
    let buf = Buffer.alloc(0);
    client.on("data", (chunk) => {
      buf = Buffer.concat([buf, chunk]);
      if (buf.length >= 4) {
        const len = buf.readUInt32BE(0);
        if (buf.length >= 4 + len) {
          resolve(JSON.parse(buf.subarray(4, 4 + len).toString()));
          client.end();
        }
      }
    });
    client.on("error", reject);
  });
}

tcpCall("package/list").then(console.log);

python

import socket, struct, json

def tcp_call(path: str, params: dict = None,
             host="127.0.0.1", port=18186) -> dict:
    payload = json.dumps({"path": path, "params": params or {}}).encode()
    with socket.create_connection((host, port)) as sock:
        sock.sendall(struct.pack(">I", len(payload)) + payload)
        length = struct.unpack(">I", sock.recv(4))[0]
        data = b""
        while len(data) < length:
            data += sock.recv(length - len(data))
        return json.loads(data)

result = tcp_call("package/list")
print(result)

kotlin

import java.io.DataInputStream
import java.io.DataOutputStream
import java.net.Socket

fun tcpCall(path: String, params: String = "{}",
            host: String = "127.0.0.1", port: Int = 18186): String {
    Socket(host, port).use { socket ->
        val output = DataOutputStream(socket.getOutputStream())
        val input = DataInputStream(socket.getInputStream())
        val payload = """{"path":"$path","params":$params}""".toByteArray()
        output.writeInt(payload.size)
        output.write(payload)
        output.flush()
        val length = input.readInt()
        val response = ByteArray(length)
        input.readFully(response)
        return String(response)
    }
}

val result = tcpCall("package/list")
println(result)

java

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.net.Socket;

public static String tcpCall(String path) throws Exception {
    try (Socket socket = new Socket("127.0.0.1", 18186)) {
        DataOutputStream out = new DataOutputStream(socket.getOutputStream());
        DataInputStream in = new DataInputStream(socket.getInputStream());

        byte[] payload = ("{\"path\":\"" + path + "\",\"params\":{}}").getBytes();
        out.writeInt(payload.length);
        out.write(payload);
        out.flush();

        int length = in.readInt();
        byte[] response = new byte[length];
        in.readFully(response);
        return new String(response);
    }
}

// 调用
System.out.println(tcpCall("package/list"));

package main

import (
    "encoding/binary"
    "encoding/json"
    "fmt"
    "io"
    "net"
)

func tcpCall(path string, params map[string]any) (map[string]any, error) {
    conn, err := net.Dial("tcp", "127.0.0.1:18186")
    if err != nil {
        return nil, err
    }
    defer conn.Close()

    payload, _ := json.Marshal(map[string]any{"path": path, "params": params})
    header := make([]byte, 4)
    binary.BigEndian.PutUint32(header, uint32(len(payload)))
    conn.Write(header)
    conn.Write(payload)

    if _, err := io.ReadFull(conn, header); err != nil {
        return nil, err
    }
    buf := make([]byte, binary.BigEndian.Uint32(header))
    if _, err := io.ReadFull(conn, buf); err != nil {
        return nil, err
    }
    var result map[string]any
    json.Unmarshal(buf, &result)
    return result, nil
}

func main() {
    result, _ := tcpCall("package/list", nil)
    fmt.Println(result)
}

4. 命令行 (CLI) 调用

在云机内通过 ca 工具直接调用：

基本用法: ca <接口路径> [--参数名参数值 ...]
查看所有接口: ca list

以「获取已安装应用列表」为例：

bash

ca package/list

5. MCP 调用（AI Agent 集成）

需要 API 版本 1.0.7 及以上

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

SSE 端点（二选一）：

模式	端点
局域网模式（勾选局域网IP）	`http://{云机IP}:18185/mcp/sse`
非局域网模式（未勾选局域网IP）	`http://{主机IP}:18182/android_api/v2/{云机ID}/mcp/sse`

以下配置以局域网模式为例，非局域网模式将 URL 替换为云机外 HTTP 调用地址即可。

bash

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

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

yaml

# ~/.codex/config.yaml
mcp_servers:
  vmos-edge-control-api:
    type: sse
    url: "http://{云机IP}:18185/mcp/sse"

json

// ~/.gemini/settings.json
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "httpUrl": "http://{云机IP}:18185/mcp/sse"
    }
  }
}

json

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

json

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

连接成功后，AI 可直接调用截图、点击、输入文本、查看 UI 层次等工具，无需手动构造 HTTP 请求。

参数格式支持

所有支持 POST 方法的接口，除了标准的 application/json 外，还支持 application/yaml 格式。

JSON 格式 (默认)

Content-Type: application/json

YAML 格式

Content-Type: application/yaml 或 text/yaml
示例:
yaml
```
package_name: com.android.settings
```

通用响应结构

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

json

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

基础能力 (Base)

获取 API 版本

获取当前控制服务的版本信息以及所有支持的接口路径。需要镜像版本 20260113 及以上支持。

URL: /base/version_info
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "version_name": "1.0.0",
    "version_code": 100,
    "supported_list": [
      "base/sleep",
      "workflow",
      "base/version_info",
      "..."
    ]
  },
  "msg": "OK",
  "request_id": "si123456"
}

暂停响应

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

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

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

返回示例:

json

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

工作流 (Workflow)

执行工作流

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

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

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

请求示例 (JSON):

json

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

请求示例 (YAML):

yaml

actions:
  - path: activity/start
    params:
      package_name: com.android.settings
  - path: base/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、OBB 等分包格式。通过文件上传（multipart）方式安装。

URL: /package/install_sync
方式: POST
参数:
参数名类型必选说明
file file 是 APK/XAPK 文件（multipart/form-data）
installer_package_name string 否指定安装来源包名

参数名	类型	必选	说明
file	file	是	APK/XAPK 文件（multipart/form-data）
installer_package_name	string	否	指定安装来源包名

文件上传注意事项：使用 file（multipart）上传时，installer_package_name 等文本参数必须放在 file 字段之前，或通过 Query 参数传递（推荐）。示例：
POST /package/install_sync?installer_package_name=com.android.vending
Content-Type: multipart/form-data

file=@app.xapk

返回示例:

json

{
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.apkmirror.helper.prod",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

通过 URI 安装应用

需要 API 版本 1.0.7 及以上

仅支持 URI 方式安装，不支持文件上传。适用于已有 APK 下载链接或本地路径的场景。同步等待安装完成后返回结果。支持标准 APK 及 APKS、APKM、XAPK、OBB 等分包格式。

URL: /package/install_uri_sync
方式: POST
参数:
参数名类型必选说明
uri string 是 APK URI，支持 http://、https://（自动下载后安装）、file://、content:// 或本地路径
installer_package_name string 否指定安装来源包名

参数名	类型	必选	说明
uri	string	是	APK URI，支持 `http://`、`https://`（自动下载后安装）、`file://`、`content://` 或本地路径
installer_package_name	string	否	指定安装来源包名

请求示例:

json

{
  "uri": "https://example.com/app.apk"
}

返回示例:

json

{
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.example.app",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

卸载应用

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 是文件字段，支持多个文件
scan boolean 否是否扫描媒体库，默认 true，只扫描多媒体文件

参数名	类型	必选	说明
dir_path	string	是	目标目录 (如 `/sdcard/Download/`)
file	file	是	文件字段，支持多个文件
scan	boolean	否	是否扫描媒体库，默认 `true`，只扫描多媒体文件

返回示例:

json

{
  "code": 200,
  "data": {
    "files": [
      {
        "file_path": "/sdcard/Download/image.jpg",
        "file_size": 123456,
        "scanned": true,
        "mime_type": "image/jpeg"
      }
    ]
  },
  "msg": "OK",
  "request_id": "t0u1v2w3x4y5z6a7b8c9"
}

导出文件

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

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

扫描媒体文件

扫描指定的媒体文件到系统媒体库。只扫描图片、视频和音频文件。需要 API 版本 1.0.4 及以上支持。

URL: /file/media_scan
方式: POST
Content-Type: application/json
参数:
参数名类型必选说明
paths array 是文件路径列表
mime_types array 是 MIME 类型列表，与 paths 一一对应

参数名	类型	必选	说明
paths	array	是	文件路径列表
mime_types	array	是	MIME 类型列表，与 paths 一一对应

请求示例:

json

{
  "paths": [
    "/sdcard/Download/image.jpg",
    "/sdcard/Download/video.mp4"
  ],
  "mime_types": [
    "image/jpeg",
    "video/mp4"
  ]
}

返回示例:

json

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

说明:
- paths 和 mime_types 必须一一对应，数量必须相同
- 只扫描多媒体文件（图片、视频、音频），其他文件类型会被自动过滤
- 如果路径对应的文件不存在或不是文件，会被跳过
- 返回 true 表示成功，false 表示失败

HTTP下载文件

需要 API 版本 1.0.7 及以上

URL: /file/download
方式: POST
参数:
参数名类型必选说明
url string 是下载地址（支持 http/https）
path string 是保存路径（如 /sdcard/Download/file.zip）
overwrite boolean 否是否覆盖已存在文件，默认 true

参数名	类型	必选	说明
url	string	是	下载地址（支持 http/https）
path	string	是	保存路径（如 `/sdcard/Download/file.zip`）
overwrite	boolean	否	是否覆盖已存在文件，默认 `true`

返回示例:

json

{
  "code": 200,
  "data": {
    "path": "/sdcard/Download/file.zip",
    "size": 1048576
  },
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

列出目录内容

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

更新系统设置

更新系统时区、语言和地区。需要镜像版本 20260113 及以上支持。

URL: /system/update_settings
方式: POST
参数:
参数名类型必选说明
timezone string 否时区 ID (如 Asia/Shanghai)
language string 否语言代码 (如 zh)
region string 否国家/地区代码 (如 CN)

参数名	类型	必选	说明
timezone	string	否	时区 ID (如 `Asia/Shanghai`)
language	string	否	语言代码 (如 `zh`)
region	string	否	国家/地区代码 (如 `CN`)

请求示例:

json

{
  "timezone": "Asia/Shanghai",
  "language": "zh",
  "region": "CN"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "timezone": "Asia/Shanghai",
    "language": "zh",
    "region": "CN"
  },
  "msg": "OK",
  "request_id": "us123456"
}

设置系统属性

设置 Android 系统属性 (System Properties)。需要镜像版本 20260113 及以上支持。

URL: /system/set_prop
方式: POST
参数:
参数名类型必选说明
properties object 否属性键值对 (Key-Value)，直接使用指定的 key
persist_properties object 否属性键值对 (Key-Value)，key 会自动加上系统前缀

参数名	类型	必选	说明
properties	object	否	属性键值对 (Key-Value)，直接使用指定的 key
persist_properties	object	否	属性键值对 (Key-Value)，key 会自动加上系统前缀

请求示例:

json

{
  "properties": {
    "persist.sys.test": "value1",
    "debug.test": "value2"
  },
  "persist_properties": {
    "test": "value1",
    "key2": "value2"
  }
}

说明:
- properties 中的 key 会直接使用，如 persist.sys.test 会设置为 persist.sys.test
- persist_properties 中的 key 会自动加上系统前缀
- 至少需要提供 properties 或 persist_properties 其中一个参数

返回示例:

json

{
  "code": 200,
  "data": {
    "persist.sys.test": true,
    "debug.test": true,
    "test": true,
    "key2": true
  },
  "msg": "OK",
  "request_id": "sp123456"
}

修改系统设置项

需要 API 版本 1.0.7 及以上

URL: /system/settings_put
方式: POST
说明: 等同于 settings put <namespace> <key> <value>，支持 secure / global / system 三个命名空间
参数:
参数名类型必选说明
namespace string 是命名空间，可选值：secure、global、system
key string 是设置项 key，如 default_input_method
value string 是要设置的值

参数名	类型	必选	说明
namespace	string	是	命名空间，可选值：`secure`、`global`、`system`
key	string	是	设置项 key，如 `default_input_method`
value	string	是	要设置的值

请求示例:

json

{
  "namespace": "secure",
  "key": "default_input_method",
  "value": "com.example.ime/.InputMethodService"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sp123456"
}

查询系统设置项

需要 API 版本 1.0.7 及以上

URL: /system/settings_get
方式: POST
说明: 等同于 settings get <namespace> <key>，支持 secure / global / system 三个命名空间
参数:
参数名类型必选说明
namespace string 是命名空间，可选值：secure、global、system
key string 是设置项 key，如 default_input_method

参数名	类型	必选	说明
namespace	string	是	命名空间，可选值：`secure`、`global`、`system`
key	string	是	设置项 key，如 `default_input_method`

请求示例:

json

{
  "namespace": "secure",
  "key": "default_input_method"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sg123456"
}

电源管理 (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"
}

电池管理 (Battery)

获取电池信息

获取当前设备的电池状态信息。返回的数据为 Android BatteryManager Intent 的原始 extras 数据。

URL: /battery/get
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 3,
    "plugged": 0,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 47,
    "scale": 100,
    "temperature": 338,
    "voltage": 3036,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bg123456"
}

返回字段说明:

字段名	类型	说明
level	int	当前电量值 (0-scale)，-1 表示未知
scale	int	最大电量值，通常为 100
status	int	电池状态，见下表
plugged	int	充电器连接类型，见下表
health	int	电池健康状态，见下表
voltage	int	电池电压 (mV)，-1 表示未知
temperature	int	电池温度 (0.1°C，需除以10得到摄氏度)，-1 表示未知
technology	string	电池技术类型 (如 `Li-ion`)，可能为 null
present	boolean	是否存在电池
icon-small	int	电池图标资源 ID
max_charging_voltage	int	最大充电电压 (微伏，需除以1000000得到伏特)
max_charging_current	int	最大充电电流 (微安，需除以1000000得到安培)
seq	int	电池状态序列号
charge_counter	int	电池充电计数器
invalid_charger	int	无效充电器标识：`0`=有效、`1`=无效
battery_low	boolean	是否低电量

status 电池状态:
值常量名说明
1 BATTERY_STATUS_UNKNOWN 未知
2 BATTERY_STATUS_CHARGING 充电中
3 BATTERY_STATUS_DISCHARGING 放电中
4 BATTERY_STATUS_NOT_CHARGING 未充电
5 BATTERY_STATUS_FULL 已充满

值	常量名	说明
1	BATTERY_STATUS_UNKNOWN	未知
2	BATTERY_STATUS_CHARGING	充电中
3	BATTERY_STATUS_DISCHARGING	放电中
4	BATTERY_STATUS_NOT_CHARGING	未充电
5	BATTERY_STATUS_FULL	已充满

health 电池健康:

值	常量名	说明
1	BATTERY_HEALTH_UNKNOWN	未知
2	BATTERY_HEALTH_GOOD	良好
3	BATTERY_HEALTH_OVERHEAT	过热
4	BATTERY_HEALTH_DEAD	损坏
5	BATTERY_HEALTH_OVER_VOLTAGE	过压
6	BATTERY_HEALTH_UNSPECIFIED_FAILURE	未知故障
7	BATTERY_HEALTH_COLD	过冷

plugged 充电方式:
值常量名说明
0 - 未连接
1 BATTERY_PLUGGED_AC AC充电
2 BATTERY_PLUGGED_USB USB充电
4 BATTERY_PLUGGED_WIRELESS 无线充电

值	常量名	说明
0	-	未连接
1	BATTERY_PLUGGED_AC	AC充电
2	BATTERY_PLUGGED_USB	USB充电
4	BATTERY_PLUGGED_WIRELESS	无线充电

设置电池信息

设置设备的电池信息，支持设置电量、状态、健康状态、温度、电压等参数。需要 API 版本 1.0.4 及以上支持。

URL: /battery/set
方式: POST

参数:

参数名	类型	必选	说明
level	int	否	电池电量 (0-100)
status	int	否	电池状态，见 `/battery/get` 接口说明
health	int	否	电池健康，见 `/battery/get` 接口说明
plugged	int	否	充电方式，见 `/battery/get` 接口说明

请求示例:

json

{
  "level": 85,
  "status": 2,
  "health": 2,
  "plugged": 2
}

返回示例:

json

{
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 2,
    "plugged": 2,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 85,
    "scale": 100,
    "temperature": 300,
    "voltage": 4200,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bs123456"
}

说明:
- 返回数据为设置后的最新电池信息，格式与 /battery/get 接口相同
- 至少需要提供一个参数，否则会返回错误
- level 参数会被自动限制在 0-100 范围内
- status 和 health 参数必须为有效的枚举值，否则设置会被忽略
- 返回字段说明请参考 /battery/get 接口

本地化 (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 字节。

通话记录 (CallLog)

添加通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/add
方式: POST
参数:
参数名类型必选说明
number string 是电话号码
type int 否类型：1=来电, 2=去电, 3=未接 (默认 1)
date long 否时间戳，默认当前时间
duration long 否通话时长 (秒)，默认 0

参数名	类型	必选	说明
number	string	是	电话号码
type	int	否	类型：1=来电, 2=去电, 3=未接 (默认 1)
date	long	否	时间戳，默认当前时间
duration	long	否	通话时长 (秒)，默认 0

请求示例:

json

{
  "number": "13800001234",
  "type": 1,
  "duration": 60
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    }
  ],
  "msg": "OK",
  "request_id": "cla123456"
}

批量添加通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/add_list
方式: POST
参数:
参数名类型必选说明
calllog_list array 是通话记录列表，每项包含 number, type, date, duration

参数名	类型	必选	说明
calllog_list	array	是	通话记录列表，每项包含 `number`, `type`, `date`, `duration`

请求示例:

json

{
  "list": [
    { "number": "13800001234", "type": 1, "duration": 60 },
    { "number": "13900005678", "type": 2, "duration": 120 }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    },
    {
      "_id": 2,
      "number": "13900005678",
      "type": 2,
      "type_name": "OUTGOING_TYPE",
      "date": 1678888889000,
      "duration": 120,
      "new": 0,
      "cached_name": null
    }
  ],
  "msg": "OK",
  "request_id": "clal123456"
}

删除通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/delete
方式: POST
参数:
参数名类型必选说明
id long 是通话记录 ID

参数名	类型	必选	说明
id	long	是	通话记录 ID

返回示例:

json

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

批量删除通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是通话记录 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cldl123456"
}

说明: 返回数据为成功删除的记录条数。

清空通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 15,
  "msg": "OK",
  "request_id": "clc123456"
}

说明: 返回数据为删除的记录条数。

获取通话记录列表

需要 API 版本 1.0.4 及以上支持。

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

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "number": "13800001234",
        "type": 1,
        "type_name": "INCOMING_TYPE",
        "date": 1678888888000,
        "duration": 60,
        "new": 0,
        "cached_name": "张三",
        "contact": {
          "_id": 3,
          "display_name": "张三"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "cll123456"
}

返回字段说明:

字段名	类型	说明
_id	long	通话记录唯一 ID
number	string	电话号码
type	int	通话类型：1=来电, 2=去电, 3=未接, 4=语音信箱, 5=拒接, 6=拦截
type_name	string	通话类型常量名 (如 `INCOMING_TYPE`)
date	long	通话时间戳 (ms)
duration	long	通话时长 (秒)
new	int	是否为新记录：1=是, 0=否
cached_name	string	联系人姓名缓存 (可能为 null)
contact	object	联系人信息 (号码匹配时返回，包含 `_id` 和 `display_name`)

联系人管理 (Contact)

添加联系人

需要 API 版本 1.0.4 及以上支持。

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

请求示例:

json

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

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "张三",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    }
  ],
  "msg": "OK",
  "request_id": "con1234567890"
}

批量添加联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/add_list
方式: POST
参数:
参数名类型必选说明
contact_list array 是联系人列表，每项包含 name, phone, email, organization, title, note

请求示例:

json

{
  "contact_list": [
    { "name": "张三", "phone": "13800138000" },
    { "name": "李四", "phone": "13900139000", "email": "lisi@example.com" }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "张三",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    },
    {
      "_id": 2,
      "display_name": "李四",
      "has_phone_number": 1,
      "phones": ["13900139000"]
    }
  ],
  "msg": "OK",
  "request_id": "cal123456"
}

删除联系人

需要 API 版本 1.0.4 及以上支持。

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

返回示例:

json

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

批量删除联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是联系人 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cdl123456"
}

说明: 返回数据为成功删除的记录条数。

获取联系人列表

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

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "张三",
        "has_phone_number": 1,
        "phones": ["13800138000"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cl123456"
}

返回字段说明:
字段名类型说明
_id long 联系人唯一 ID
display_name string 联系人显示名称
has_phone_number int 是否有电话号码：1=有, 0=无
phones array 电话号码列表

条件查询联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/query
方式: POST
参数:
参数名类型必选说明
id long 否联系人 ID
name string 否联系人姓名（模糊匹配）
phone string 否电话号码
offset int 否偏移量，默认 0
limit int 否限制数量，默认 100
请求示例:
json
```
{
  "name": "张"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "张三",
        "has_phone_number": 1,
        "phones": ["13800001234"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cq123456"
}

说明: 支持按 ID、姓名（模糊匹配）、电话号码查询联系人。参数可组合使用，不传参数则返回所有联系人。

清空联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 5,
  "msg": "OK",
  "request_id": "cc123456"
}

说明: 返回数据为删除的记录条数。

短信管理 (SMS)

获取短信列表

URL: /sms/list
方式: GET

参数:

参数名	类型	必选	说明
type	int	否	短信类型 (0: 所有, 1: 收件箱, 2: 已发送, 3: 草稿, 4: 待发送, 5: 失败, 6: 队列)，默认 0
offset	int	否	偏移量，默认 0
limit	int	否	限制数量，默认 100

返回示例:

json

{
  "code": 200,
  "data": {
    "type": 0,
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "address": "13800001234",
        "body": "这是一条测试短信",
        "date": 1736412345000,
        "type": 1,
        "type_name": "MESSAGE_TYPE_INBOX",
        "read": 1,
        "seen": 1,
        "creator": "com.android.messaging",
        "contact": {
          "_id": 3,
          "display_name": "张三"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "sl123456"
}

返回字段说明:

字段名	类型	说明
_id	long	短信唯一 ID
address	string	对方号码
body	string	短信内容
date	long	时间戳 (ms)
type	int	短信类型：1=收件箱, 2=已发送, 3=草稿, 4=待发送, 5=失败, 6=队列
type_name	string	短信类型常量名 (如 `MESSAGE_TYPE_INBOX`)
read	int	是否已读：1=是, 0=否
seen	int	是否已展示：1=是, 0=否
creator	string	创建者包名
contact	object	联系人信息 (号码匹配时返回，包含 `_id` 和 `display_name`)

添加短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/add
方式: POST

参数:

参数名	类型	必选	说明
address	string	是	对方号码
body	string	是	短信内容
type	int	否	短信类型 (1: 收件箱, 2: 已发送, 3: 草稿, 4: 待发送, 5: 失败, 6: 队列)，默认 1
date	long	否	时间戳，默认当前时间
read	boolean	否	是否已读，默认 `true`
seen	boolean	否	是否已展示，默认 `true`

请求示例:

json

{
  "address": "13800001234",
  "body": "这是一条测试短信。",
  "type": 1,
  "read": true,
  "seen": true
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "这是一条测试短信。",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    }
  ],
  "msg": "OK",
  "request_id": "sa123456"
}

批量添加短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/add_list
方式: POST
参数:
参数名类型必选说明
sms_list array 是短信列表，每项包含 address, body, type, date, read, seen

请求示例:

json

{
  "list": [
    { "address": "13800001234", "body": "测试短信1", "type": 1 },
    { "address": "13900005678", "body": "测试短信2", "type": 1 }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "测试短信1",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    },
    {
      "_id": 2,
      "address": "13900005678",
      "body": "测试短信2",
      "date": 1736412346000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging"
    }
  ],
  "msg": "OK",
  "request_id": "sal123456"
}

接收短信（模拟发送短信）

模拟接收短信，会触发系统短信接收流程。需要 API 版本 1.0.4 及以上支持，当前支持 Android 13 / 14。

URL: /sms/receive
方式: POST
参数:
参数名类型必选说明
sender string 是发送者号码
body string 是短信内容

请求示例:

json

{
  "sender": "13800001234",
  "body": "您的验证码是 123456。"
}

返回示例:

json

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

说明: 与 /sms/add 的区别是，此接口会触发完整的短信接收流程，包括系统通知、广播等，而 /sms/add 只是向数据库中添加记录。

删除短信

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

返回示例:

json

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

批量删除短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是短信 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "sdl123456"
}

说明: 返回数据为成功删除的记录条数。

清空短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 20,
  "msg": "OK",
  "request_id": "sc123456"
}

说明: 返回数据为删除的记录条数。

位置管理 (Location)

获取位置信息

获取当前设备的 GPS 位置信息。需要 API 版本 1.0.4 及以上支持。

URL: /location/get_data
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "latitude": 39.9042,
    "longitude": 116.4074,
    "altitude": 0.0,
    "speed": 0.0,
    "bearing": 0.0,
    "accuracy": 50.0,
    "vertical_accuracy_meters": 50.0,
    "speed_accuracy_meters_per_second": 1.0,
    "bearing_accuracy_degrees": 30.0,
    "enabled": true,
    "time": 1673641234567,
    "provider": "gps"
  },
  "msg": "OK",
  "request_id": "lg123456"
}

返回字段说明:

字段名	类型	说明
latitude	double	纬度
longitude	double	经度
altitude	double	海拔 (米)
speed	double	速度 (米/秒)
bearing	double	方向 (角度)
accuracy	float	水平精度 (米)
vertical_accuracy_meters	float	垂直精度 (米)
speed_accuracy_meters_per_second	float	速度精度 (米/秒)
bearing_accuracy_degrees	float	方向精度 (角度)
enabled	boolean	模拟定位是否已开启
time	long	位置获取的时间戳 (ms)
provider	string	位置提供者 (如 `gps`, `network`, `properties`)

设置位置信息

模拟设备的 GPS 位置信息。需要 API 版本 1.0.4 及以上支持。

URL: /location/set_data
方式: POST

参数:

参数名	类型	必选	说明
enabled	boolean	否	是否开启模拟定位
persist	boolean	否	是否持久化（重启后是否生效），默认 `false`
latitude	double	否	纬度
longitude	double	否	经度
altitude	double	否	海拔 (米)，默认 `0.0`
speed	double	否	速度 (米/秒)，默认 `0.0`
bearing	double	否	方向 (角度)，默认 `0.0`
accuracy	double	否	水平精度 (米)，默认 `50.0`
vertical_accuracy_meters	double	否	垂直精度 (米)，默认 `50.0`
speed_accuracy_meters_per_second	double	否	速度精度 (米/秒)，默认 `1.0`
bearing_accuracy_degrees	double	否	方向精度 (角度)，默认 `30.0`

请求示例:

json

{
  "latitude": 39.9042,
  "longitude": 116.4074,
  "vertical_accuracy_meters": 50.0,
  "enabled": true,
  "persist": true
}

返回示例:

json

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

传感器管理 (Sensor)

获取传感器列表

获取系统支持的所有传感器信息。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/list
方式: GET
参数:
参数名类型必选说明
type int 否传感器类型 ID，不传则返回所有

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "name": "Goldfish 3-axis Accelerometer",
      "type": 1,
      "type_name": "TYPE_ACCELEROMETER",
      "vendor": "The Android Open Source Project",
      "version": 1,
      "resolution": 0.0,
      "power": 0.0,
      "min_delay": 0,
      "string_type": "android.sensor.accelerometer"
    }
  ],
  "msg": "OK",
  "request_id": "sl123456"
}

返回字段说明:

字段名	类型	说明
name	string	传感器名称
type	int	传感器类型 ID
type_name	string	传感器类型常量名
vendor	string	传感器厂商
version	int	传感器版本
resolution	float	传感器分辨率
power	float	功耗 (mA)
min_delay	int	最小采样间隔 (微秒)
string_type	string	传感器类型字符串

获取传感器数据

获取当前传感器的实时数据。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/get_data
方式: GET
参数:
参数名类型必选说明
type int 否传感器类型 ID (如 1=加速度)，不传则返回所有传感器数据
timeout long 否获取数据的超时时间 (ms)，默认 500

返回示例 (单个传感器):

json

{
  "code": 200,
  "data": {
    "type": 1,
    "type_name": "TYPE_ACCELEROMETER",
    "name": "Goldfish 3-axis Accelerometer",
    "values": [0.0, 9.8, 0.0],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}

返回示例 (所有传感器):

json

{
  "code": 200,
  "data": {
    "sensors": [
      {
        "type": 1,
        "type_name": "TYPE_ACCELEROMETER",
        "name": "Goldfish 3-axis Accelerometer",
        "values": [0.0, 9.8, 0.0]
      }
    ],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}

设置传感器数据

设置虚拟传感器的模拟数据。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/set_data
方式: POST
参数:
参数名类型必选说明
sensors array 是传感器数据列表

Sensor 对象说明:

参数名	类型	必选	说明
type	int	是	传感器类型，见下表
value	double	否	单值传感器的值 (如光线、压力、距离、湿度、温度、步数等)
x	double	否	三轴传感器的 X 轴值 (如加速度、磁场、陀螺仪等)
y	double	否	三轴传感器的 Y 轴值
z	double	否	三轴传感器的 Z 轴值

传感器类型:

type	常量名	说明
1	TYPE_ACCELEROMETER	加速度传感器
2	TYPE_MAGNETIC_FIELD	磁场传感器
3	TYPE_ORIENTATION	方向传感器
4	TYPE_GYROSCOPE	陀螺仪传感器
5	TYPE_LIGHT	光线传感器
6	TYPE_PRESSURE	压力传感器
8	TYPE_PROXIMITY	距离传感器
9	TYPE_GRAVITY	重力传感器
10	TYPE_LINEAR_ACCELERATION	线性加速度传感器
11	TYPE_ROTATION_VECTOR	旋转向量传感器
12	TYPE_RELATIVE_HUMIDITY	湿度传感器
13	TYPE_AMBIENT_TEMPERATURE	温度传感器
14	TYPE_MAGNETIC_FIELD_UNCALIBRATED	未校准磁场传感器
15	TYPE_GAME_ROTATION_VECTOR	游戏旋转向量传感器
16	TYPE_GYROSCOPE_UNCALIBRATED	未校准陀螺仪传感器
17	TYPE_SIGNIFICANT_MOTION	显著运动传感器
18	TYPE_STEP_DETECTOR	步数检测传感器
19	TYPE_STEP_COUNTER	步数计数传感器
20	TYPE_GEOMAGNETIC_ROTATION_VECTOR	地磁旋转向量传感器
21	TYPE_HEART_RATE	心率传感器
22	TYPE_TILT_DETECTOR	倾斜检测传感器
25	TYPE_PICK_UP_GESTURE	拿起手势传感器
26	TYPE_WRIST_TILT_GESTURE	手腕倾斜传感器
27	TYPE_DEVICE_ORIENTATION	设备方向传感器
30	TYPE_MOTION_DETECT	运动检测传感器
35	TYPE_ACCELEROMETER_UNCALIBRATED	未校准加速度传感器
36	TYPE_HINGE_ANGLE	铰链角度传感器

请求示例:

json

{
  "sensors": [
    {
      "type": 5,
      "value": 100.0
    },
    {
      "type": 2,
      "x": 1.0,
      "y": 2.0,
      "z": 3.0
    }
  ]
}

返回示例:

json

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

账号管理 (Account)

添加账号

URL: /account/add
方式: POST
参数:
参数名类型必选说明
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 否过滤账号类型

返回示例:

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

返回示例:

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

返回示例:

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 节点操作

统一的节点查找与操作接口，支持查找、等待、执行动作。需要镜像版本 20260201 及以上支持。

URL: /accessibility/node
方式: POST

参数:

参数名	类型	必选	说明
selector	object	是	节点选择器，包含查找条件
wait_timeout	long	否	等待超时时间 (ms)，默认 0 表示不等待
wait_interval	long	否	等待间隔 (ms)，默认 500
action	string	否	要执行的动作名称 (如 `click`, `set_text`)
action_params	object	否	动作参数 (如 `text`)
action_index	int	否	对第几个匹配的节点执行动作，默认 0

Selector 选择器参数:

参数名	类型	必选	说明
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 坐标

支持的 Action 动作:
- click: 点击
- long_click: 长按
- set_text: 设置文本 (需参数 text)
- clear_text: 清除文本
- scroll_forward / scroll_backward: 向前/向后滚动
- scroll_up / scroll_down / scroll_left / scroll_right: 方向滚动
- focus / clear_focus: 获取/清除焦点
- select / clear_selection: 选中/取消选中
- copy / paste / cut: 剪贴板操作
- expand / collapse: 展开/折叠
- ime_enter: 输入法确定

请求示例 (文本精准匹配):

json

{
  "selector": {
    "text": "设置"
  },
  "action": "click"
}

请求示例 (XPath 匹配):

json

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

请求示例 (等待并设置文本):

json

{
  "selector": {
    "resource_id": "com.example:id/input"
  },
  "wait_timeout": 5000,
  "action": "set_text",
  "action_params": {
    "text": "Hello"
  }
}

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "nodes": [ ... ],
    "action": "click",
    "action_index": 0,
    "action_node": { ... }
  },
  "msg": "OK",
  "request_id": "an123456"
}

设置无障碍服务隐藏状态

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

URL: /accessibility/set_hidden
方式: POST
参数:
参数名类型必选说明
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 否过滤指定应用的通知

返回示例:

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. TCP 调用 ​

4. 命令行 (CLI) 调用 ​

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

参数格式支持 ​

JSON 格式 (默认) ​

YAML 格式 ​

通用响应结构 ​

基础能力 (Base) ​

获取 API 版本 ​

暂停响应 ​

工作流 (Workflow) ​

执行工作流 ​

应用运行管理 (Activity) ​

启动应用 ​

启动指定 Activity ​

停止应用 ​

获取正在运行的进程 ​

获取最上层组件信息 ​

获取最近任务列表 ​

清空任务栈 ​

切换任务到前台 ​

应用管理 (Package) ​

安装应用 ​

通过 URI 安装应用 ​

卸载应用 ​

设置应用启用状态 ​

获取已安装应用列表 ​

导出应用 APK ​

清除应用数据 ​

输入控制 (Input) ​

点击 ​

多击 ​

输入文本 ​

按键 ​

滑动 ​

曲线滑动 ​

发送原始 MotionEvent 事件 ​

权限管理 (Permission) ​

获取应用权限 ​

设置应用权限 ​

文件管理 (File) ​

导入文件 ​

导出文件 ​

扫描媒体文件 ​

HTTP下载文件 ​

列出目录内容 ​

系统设置 (System) ​

执行 Shell 命令 ​

设置壁纸 ​

更新系统设置 ​

设置系统属性 ​

修改系统设置项 ​

查询系统设置项 ​

电源管理 (Power) ​

点亮 / 熄灭屏幕 ​

锁定 / 解锁屏幕 ​

获取屏幕与锁屏状态 ​

电池管理 (Battery) ​

获取电池信息 ​

设置电池信息 ​

本地化 (Locale) ​

获取本地化信息 ​

剪贴板 (Clipboard) ​

设置剪贴板 ​

获取当前剪贴板 ​

获取剪贴板历史列表 ​

清空剪贴板 ​

屏幕与显示 (Display) ​

获取屏幕信息 ​

屏幕旋转 ​

屏幕截图（压缩） ​

获取截图 ​

通话记录 (CallLog) ​

添加通话记录 ​

批量添加通话记录 ​

Android Control API 接口文档

简介

调用方式

1. 云机外 HTTP 调用

2. 云机内 HTTP 调用

3. TCP 调用

4. 命令行 (CLI) 调用

5. MCP 调用（AI Agent 集成）

参数格式支持

JSON 格式 (默认)

YAML 格式

通用响应结构

基础能力 (Base)

获取 API 版本

暂停响应

工作流 (Workflow)

执行工作流

应用运行管理 (Activity)

启动应用

启动指定 Activity

停止应用

获取正在运行的进程

获取最上层组件信息

获取最近任务列表

清空任务栈

切换任务到前台

应用管理 (Package)

安装应用

通过 URI 安装应用

卸载应用

设置应用启用状态

获取已安装应用列表

导出应用 APK

清除应用数据

输入控制 (Input)

点击

多击

输入文本

按键

滑动

曲线滑动

发送原始 MotionEvent 事件

权限管理 (Permission)

获取应用权限

设置应用权限

文件管理 (File)

导入文件

导出文件

扫描媒体文件

HTTP下载文件

列出目录内容

系统设置 (System)

执行 Shell 命令

设置壁纸

更新系统设置

设置系统属性

修改系统设置项

查询系统设置项

电源管理 (Power)

点亮 / 熄灭屏幕

锁定 / 解锁屏幕

获取屏幕与锁屏状态

电池管理 (Battery)

获取电池信息

设置电池信息

本地化 (Locale)

获取本地化信息

剪贴板 (Clipboard)

设置剪贴板

获取当前剪贴板

获取剪贴板历史列表

清空剪贴板

屏幕与显示 (Display)

获取屏幕信息

屏幕旋转

屏幕截图（压缩）

获取截图

通话记录 (CallLog)

添加通话记录

批量添加通话记录