ArmCloud OpenAPI 开发者速查手册

ArmCloud 云手机/ARM云计算平台 OpenAPI 接口快速参考 v2.0

提示

📥 下载纯文本版本 - 适合 AI 工具直接读取

获取方式：

浏览器下载：点击上方链接或访问 https://docs.armcloud.net/llms-ai-reference.txt
命令行获取：curl https://docs.armcloud.net/llms-ai-reference.txt -o armcloud-api.txt
在线预览：浏览器中访问可查看原始文本（如遇乱码请设置编码为 UTF-8）

🔐 认证方式（必读）

本API使用V2.0签名验证方案

请求头设置（每个请求必需）

请求头	说明	示例值
authver	鉴权版本，固定值	"2.0"
x-ak	访问密钥ID（您的AccessKey）	"fsqkRdMInq14hwCv..."
x-timestamp	请求时间戳（毫秒）	"1618900299000"
x-sign	HMAC-SHA256签名（小写）	"5d9f846a525486..."

签名计算公式

待签名字符串 = timestamp + path + body
签名 = HMAC-SHA256(待签名字符串, SecretKey).toLowerCase()

说明：

timestamp: 毫秒时间戳（与x-timestamp相同）
path: API完整路径（如/openapi/open/device/list）
body:
- GET请求：查询参数字符串（如id=123&type=1）
- POST请求：紧凑JSON字符串（如{"page":1,"rows":10}，无空格无换行）

📡 基础信息

配置项	值
国内域名	`https://api.xiaosuanyun.com`
海外域名	`https://openapi-hk.armcloud.net`
响应格式	JSON `{code, msg, ts, data}`
成功状态码	`code=200`
测试用户限流	200次/秒
付费用户限流	2000次/秒

📚 API 功能分类

1️⃣ SDK Token签发

接口	方法	路径	说明
获取SDK临时Token	GET	`/openapi/open/token/stsToken`	返回sdk通信token
获取Token(padCode)	POST	`/openapi/open/token/stsTokenByPadCode`	需要参数：padCode
清除SDK授权Token	POST	`/openapi/open/token/clearStsToken`	需要参数：token
清除Token(padCode)	POST	`/openapi/open/token/clearStsTokenByPadCode`	需要参数：padCode

2️⃣ 板卡管理

接口	方法	路径	说明
板卡列表	POST	`/openapi/open/device/list`	分页查询，支持多条件筛选
查询算力使用情况	POST	`/openapi/open/device/computeUsage`	查询账户算力使用情况
板卡重启	POST	`/openapi/open/device/restartDevice`	类型：1硬重启 2断电重启
重置板卡	POST	`/openapi/open/device/resetDevice`	需要重置备注信息
查询预热成功镜像	GET	`/openapi/open/device/getLatestWarmupSuccessImages`	最多3个

板卡状态说明：

padAllocationStatus: -2删除失败 -1分配失败 0未分配 1分配中 2已分配 3删除中
deviceStatus: 0离线 1在线

3️⃣ 网存2.0（推荐）

网存2.0将实例与存储二合一，无需复杂的存储块管理，删除实例即删除对应存储

接口	方法	路径	说明
创建网存实例	POST	`/openapi/open/pad/v2/net/storage/res/create`	数量1-100个
批量开机	POST	`/openapi/open/pad/v2/net/storage/batch/boot/on`	1-200个
批量关机	POST	`/openapi/open/pad/v2/net/storage/batch/off`	1-200个
批量删除	POST	`/openapi/open/pad/v2/net/storage/batch/delete`	1-200个
批量备份	POST	`/openapi/open/pad/v2/net/storage/batch/backup`	批量备份
实例克隆	POST	`/openapi/open/pad/v2/net/storage/clone`	克隆数量1-100个
实例详情查询	POST	`/openapi/open/pad/v2/net/storage/detail`	实例详情查询

创建实例关键参数：

clusterCode: 集群代码（必填）
specificationCode: 规格代码（必填）
imageId: 镜像ID（必填）
screenLayoutCode: 屏幕布局代码（必填）
storageSize: 存储大小GB，支持：4, 8, 16, 32, 64, 128, 256（必填）

开机参数：

padCodes: 实例编码列表（必填）
timeout: 超时时间秒，范围300-7200
imageId: 镜像ID（可选，支持开机时更换，仅支持同版本镜像）

关机参数：

forceDel: 强制删除，直接关机并删除实例不保留数据（默认false，CBS版本2.3.5以上支持）

4️⃣ 网存1.0

接口	方法	路径
创建网存实例	POST	`/openapi/open/pad/net/storage/save`
网存实例开机	POST	`/openapi/open/pad/net/storage/on`
网存实例关机	POST	`/openapi/open/pad/net/storage/off`
删除网存实例	POST	`/openapi/open/pad/net/storage/delete`
查询网存集群详情	POST	`/openapi/open/net/storage/cluster/queryDetail`
设置网存集群板卡规格	POST	`/openapi/open/net/storage/cluster/setStorageDeviceLevel`
网存存储备份	POST	`/openapi/open/pad/net/storage/save/backup`
指定网存ID开机	POST	`/openapi/open/pad/net/storage/on/netStorageId`
网存存储删除	POST	`/openapi/open/pad/net/storage/delete/backup`
获取网存实例使用详情	POST	`/openapi/open/net/storage/cluster/countUsageDetail`
网存存储详情查询	POST	`/openapi/open/pad/net/storage/detail`

5️⃣ 实例管理（核心功能）

基本操作

接口	方法	路径	说明
实例详情	POST	`/openapi/open/pad/padDetails`	分页查询
实例详情-精简版	POST	`/openapi/open/pad/padBaseInfoList`	分页查询
实例列表信息	POST	`/openapi/open/pad/infos`	分页查询
实例列表-优化分页	POST	`/openapi/open/pad/infos/new`	基于lastId分页
实例重启	POST	`/openapi/open/pad/restart`	类型：1硬重启 2断电重启
实例重置	POST	`/openapi/open/pad/reset`	重置实例
一键新机	POST	`/openapi/open/pad/replacePad`	更换设备信息

属性管理

接口	方法	路径	说明
查询实例属性	POST	`/openapi/open/pad/padProperties`	单个实例
批量查询实例属性	POST	`/openapi/open/pad/batchPadProperties`	批量查询
修改实例属性	POST	`/openapi/open/pad/updatePadProperties`	通用属性修改
修改安卓改机属性	POST	`/openapi/open/pad/updatePadAndroidProp`	需重启生效
修改实例时区	POST	`/openapi/open/pad/updateTimeZone`	UTC标准时间
修改实例语言	POST	`/openapi/open/pad/updateLanguage`	语言+国家代码
修改实例SIM卡	POST	`/openapi/open/pad/updateSIM`	IMEI等信息
根据国家修改SIM卡	POST	`/openapi/open/pad/replacePadAndroidPropByCountry`	按国家代码

安卓改机属性请求示例：

{
  "padCode": "AC32010210001",
  "props": {
    "ro.product.vendor.name": "OP52D1L1",
    "ro.product.brand": "Samsung",
    "ro.product.model": "Galaxy S21"
  },
  "restart": false
}

网络与定位

接口	方法	路径	说明
修改WIFI列表	POST	`/openapi/open/pad/setWifiList`	WIFI配置
实例设置代理	POST	`/openapi/open/network/proxy/set`	HTTP代理
查询代理出口IP	POST	`/openapi/open/network/proxy/info`	代理IP查询
设置经纬度	POST	`/openapi/open/pad/gpsInjectInfo`	GPS位置注入

RTC推流

接口	方法	路径	说明
批量申请RTC Token	POST	`/rtc/open/room/batchApplyToken`	RTC连接Token
申请RTC共享Token	POST	`/rtc/open/room/share/applyToken`	共享房间Token
停止推流	POST	`/rtc/open/room/dissolveRoom`	解散房间

应用控制

接口	方法	路径	说明
查询已安装应用	POST	`/openapi/open/pad/listInstalledApp`	实时查询
设置应用自启动	POST	`/openapi/open/pad/autoBoot`	0关闭 1开启
设置应用保活	POST	`/openapi/open/pad/app/keepAlive`	保持应用运行
设置应用隐藏	POST	`/openapi/open/pad/app/hidden`	隐藏应用图标
隐藏辅助服务	POST	`/openapi/open/pad/setHideAccessibilityAppList`	隐藏辅助服务

ADB与命令

接口	方法	路径	说明
异步执行ADB命令	POST	`/openapi/open/pad/asyncCmd`	执行ADB脚本
开关Root权限	POST	`/openapi/open/pad/switchRoot`	0关闭 1开启
开启关闭ADB	POST	`/openapi/open/pad/openOnlineAdb`	0关闭 1开启
获取ADB连接信息	POST	`/openapi/open/pad/adb`	单个实例
批量获取ADB信息	POST	`/openapi/open/pad/batch/adb`	批量查询

数据注入

接口	方法	路径	说明
更新通讯录	POST	`/openapi/open/pad/updateContacts`	新增/删除/覆盖
导入通话记录	POST	`/openapi/open/pad/addPhoneRecord`	通话历史
模拟发送短信	POST	`/openapi/open/pad/simulateSendSms`	短信注入
云机文本输入	POST	`/openapi/open/pad/inputText`	输入文本
注入音频到麦克风	POST	`/openapi/open/pad/injectAudioToMic`	音频URL
无人直播	POST	`/openapi/open/pad/unmanned/live`	视频注入1-100个
图片注入	POST	`/openapi/open/pad/inject/picture`	图片注入1-100个
运动数据注入	POST	`/openapi/open/pad/stepData`	步数注入最多500个

其他功能

接口	方法	路径	说明
本地截图	POST	`/openapi/open/pad/task/screenshot`	截图任务
获取实时预览图片	POST	`/openapi/open/pad/getLongGenerateUrl`	预览URL
模拟触控	POST	`/openapi/open/pad/simulateTouch`	触控操作
重置GAID	POST	`/openapi/open/pad/resetGAID`	Google广告ID
清除进程返回桌面	POST	`/openapi/open/pad/cleanAppHome`	清理后台
设置实例带宽	POST	`/openapi/open/pad/setSpeed`	上下行带宽

镜像与模板

接口	方法	路径	说明
升级镜像	POST	`/openapi/open/pad/upgradeImage`	镜像升级
升级真机镜像	POST	`/openapi/open/pad/virtualRealSwitch`	真机镜像
修改真机ADI模板	POST	`/openapi/open/pad/replaceRealAdiTemplate`	ADI模板
分页获取真机模板	POST	`/openapi/open/realPhone/template/list`	模板列表
获取公共屏幕布局	POST	`/openapi/open/screenLayout/publicList`	布局列表
批量获取机型信息	POST	`/openapi/open/pad/modelInfo`	机型查询

黑白名单

接口	方法	路径	说明
添加应用黑名单	POST	`/openapi/open/appBlack/setUpBlackList`	黑名单配置
设置实例黑名单	POST	`/openapi/open/pad/triggeringBlacklist`	触发黑名单

分组管理

接口	方法	路径	说明
实例分组列表	POST	`/openapi/open/group/infos`	分组信息

备份还原

接口	方法	路径	说明
创建本地备份	POST	`/openapi/open/pad/data/backup`	创建本地备份
创建本地还原	POST	`/openapi/open/pad/data/restore`	创建本地还原
备份结果查询	POST	`/openapi/open/pad/local/pod/backupSelectPage`	备份列表

任务结果查询

接口	方法	路径	说明
实例操作任务详情	POST	`/openapi/open/pad/task/operate/detail`	通用任务
获取ADB执行结果	POST	`/openapi/open/pad/task/adb/detail`	ADB结果
获取截图结果	POST	`/openapi/open/pad/task/screenshot/detail`	截图URL
重启重置执行结果	POST	`/openapi/open/pad/restartOrReset/result`	重启重置

6️⃣ 文件管理

接口	方法	路径	说明
文件上传到云盘	POST	`/openapi/open/file/uploadToDisk`	multipart/form-data
文件列表	POST	`/openapi/open/file/disk/list`	分页查询
文件上传实例V3	POST	`/openapi/open/pad/v3/uploadFile`	支持URL列表
文件上传到实例V2	POST	`/openapi/open/pad/v2/uploadFile`	使用fileUniqueId
实例文件删除	POST	`/openapi/open/file/task/delete`	删除实例文件
文件任务详情	POST	`/openapi/open/file/task/detail`	任务查询

7️⃣ 应用管理

接口	方法	路径	说明
应用上传	POST	`/openapi/open/app/upload`	multipart/form-data
应用列表	POST	`/openapi/open/app/list`	分页查询
应用详情	POST	`/openapi/open/app/detail`	单个应用详情
查询实例应用列表	POST	`/openapi/open/pad/listApp`	实例已装应用
应用安装	POST	`/openapi/open/pad/installApp`	批量安装
应用卸载	POST	`/openapi/open/pad/uninstallApp`	批量卸载
应用启动	POST	`/openapi/open/pad/startApp`	启动应用
应用停止	POST	`/openapi/open/pad/stopApp`	停止应用
应用重启	POST	`/openapi/open/pad/restartApp`	重启应用
应用启停结果	POST	`/task-center/open/task/appOperateInfo`	任务结果

应用分类

接口	方法	路径	说明
应用分类列表	POST	`/openapi/open/app/category/list`	分页查询

黑白名单（旧版）

接口	方法	路径	说明
黑白名单列表	POST	`/openapi/open/appClassify/pageList`	分页查询
黑白名单保存	POST	`/openapi/open/appClassify/save`	创建名单
黑白名单详情	POST	`/openapi/open/appClassify/detail`	详情查询
实例关联保存	POST	`/openapi/open/appClassify/padSave`	关联实例
实例关联详情	POST	`/openapi/open/appClassify/padDetail`	关联查询
删除黑白名单	POST	`/openapi/open/appClassify/del`	删除
添加黑白名单App	POST	`/openapi/open/appClassify/addApp`	添加应用
添加实例关联	POST	`/openapi/open/appClassify/addPad`	添加实例
删除实例关联	POST	`/openapi/open/appClassify/delPad`	删除关联
按实例查询黑白名单	POST	`/openapi/open/appClassify/padClassifyList`	查询关联

8️⃣ 应用安全策略（推荐）

接口	方法	路径	说明
策略组列表	POST	`/openapi/open/appSecurityPolicyGroup/pageList`	分页查询
策略组详情	POST	`/openapi/open/appSecurityPolicyGroup/detail`	详情查询
保存策略组	POST	`/openapi/open/appSecurityPolicyGroup/save`	创建/更新
删除策略组	POST	`/openapi/open/appSecurityPolicyGroup/delete`	删除
变更实例策略组	POST	`/openapi/open/appSecurityPolicyGroup/changePadPolicyGroups`	变更绑定
查询实例策略组	POST	`/openapi/open/appSecurityPolicyGroup/queryPadPolicyGroups`	查询绑定
新增策略组关联	POST	`/openapi/open/appSecurityPolicyGroup/appendRelations`	追加关联
移除策略组关联	POST	`/openapi/open/appSecurityPolicyGroup/removeRelations`	移除关联

策略组类型：

0: 黑名单
1: 白名单

9️⃣ 应用安全策略V2.0

接口	方法	路径	说明
策略组列表V2	POST	`/openapi/open/newAppClassify/pageList`	新版分页

其他接口与应用安全策略相同

🔟 回调管理

接口	方法	路径	说明
查询回调类型	GET	`/openapi/open/config/selectList`	支持的回调类型
查询回调地址	GET	`/openapi/open/config/selectCallback`	当前配置
新增回调配置	POST	`/openapi/open/config/insertCallback`	添加配置
修改回调配置	POST	`/openapi/open/config/updateCallback`	更新配置
删除回调配置	POST	`/openapi/open/config/deleteCallback`	删除配置

1️⃣1️⃣ 镜像管理

接口	方法	路径	说明
获取镜像列表	POST	`/openapi/open/image/queryImageList`	分页查询

镜像信息包含：

imageId: 镜像ID
imageVersion: 镜像版本
imageDesc: 镜像描述
androidVersion: 安卓版本
supportF2fs: 是否支持f2fs

1️⃣2️⃣ 账户管理

接口	方法	路径	说明
批量新增子账户	POST	`/openapi/open/subCustomer/batchAdd`	1-30个
子账户列表	POST	`/openapi/open/subCustomer/pageList`	分页查询
子账户批量删除	POST	`/openapi/open/subCustomer/batchDelete`	删除子账户
主账号板卡列表	POST	`/openapi/open/subCustomer/resource/masterCustomer/pageList`	主账号资源
子账号板卡列表	POST	`/openapi/open/subCustomer/resource/list`	子账号资源
子账号板卡授权	POST	`/openapi/open/subCustomer/resource/allocate`	授权板卡
子账号板卡解绑	POST	`/openapi/open/subCustomer/resource/unbind`	解绑板卡
查询一键新机国家列表	GET	`/openapi/open/info/country`	国家列表

📋 回调通知事件

回调类型列表

事件	说明	关键字段
实例状态回调	实例上下线	padCode, vmStatus, eventType
实例重启任务	重启结果	taskId, padCode, status
实例重置任务	重置结果	taskId, padCode, status
ADB任务回调	ADB执行结果	taskId, padCode, result, status
应用安装任务	安装结果	taskId, padCode, packageName, status
应用卸载任务	卸载结果	taskId, padCode, packageName, status
应用启停任务	启停结果	taskId, padCode, packageName, status
文件上传任务	上传结果	taskId, padCode, filePath, status
查询应用列表	应用列表	taskId, padCode, appList
升级镜像任务	升级结果	taskId, padCode, imageId, status
实例黑名单	黑名单结果	taskId, padCode, status
一键新机	新机结果	taskId, padCode, status
网存开机	开机结果	taskId, padCode, vmStatus, status
网存关机	关机结果	taskId, padCode, vmStatus, status
网存删除	删除结果	taskId, padCode, status
网存备份	备份结果	taskId, padCode, backupId, status
网存2.0开机	开机结果	taskId, padCode, vmStatus, status
网存2.0关机	关机结果	taskId, padCode, vmStatus, status
网存2.0删除	删除结果	taskId, padCode, status
网存2.0备份	备份结果	taskId, padCode, backupId, status
订阅事件回调	事件通知	eventType, eventData

🚦 常见错误码

错误码	说明	处理建议
200	成功	-
100000	参数校验失败	检查请求参数
110020	WiFi配置参数错误	检查WIFI配置格式
110021	WiFi配置保存失败	重试或联系技术支持
110028	实例不存在	检查padCode是否正确
110030	板卡重启参数错误	检查重启类型参数
110032	板卡不存在	检查deviceIp是否正确
110033	板卡重启失败	重试或联系技术支持
110041	镜像不存在	检查imageId
110042	不属于当前用户	权限错误
110044	集群不存在	检查clusterCode
110045	规格不存在	检查specificationCode
110060	板卡不存在	检查板卡信息
110065	参数请求不合规	检查请求参数格式
110071	非网存实例	操作对象错误
110074	获取算力失败	算力不足
110075	获取IP失败	IP资源不足
110076	网段不存在	网络配置错误
110099	屏幕布局不存在	检查screenLayoutCode
111070	正在开机中	等待开机完成
111071	非关机状态	实例状态错误
111072	实例未绑定算力	算力绑定失败
111073	连续关机失败	重试或联系技术支持
111074	系统异常	联系技术支持
111075	实例删除中	等待删除完成
111076	正在关机中	等待关机完成
111077	实例非关机状态	状态错误
111078	非运行中状态	实例未运行
111079	板卡离线	板卡不在线
111080	CBS版本不支持	升级CBS版本
111081	不支持网存1.0	使用网存2.0
111082	备份数达上限/网存存储单元不存在	删除旧备份
111083	备份失败/非关机状态	关机后重试
111084	备份不存在/正在克隆中	检查备份状态
111085	存储容量不足/实例不存在开机行为	扩容或清理
111086	备份中/实例开机后未产生数据	等待或检查
111087	非关机状态/CBS版本不支持克隆	关机或升级
120008	token不属于当前用户	重新获取token
220003	镜像未预热	等待镜像预热
220009	ADI模板不存在	检查模板ID
2200014	算力不足	购买算力

💡 使用建议

1. 认证安全

妥善保管 AccessKey 和 SecretKey
不要在客户端代码中硬编码密钥
定期更换密钥

2. 限流处理

注意接口调用频率限制
使用批量接口减少调用次数
实现指数退避重试策略

3. 异步任务

重要操作配置回调接口获取结果
轮询查询时注意间隔时间
保存 taskId 用于结果查询

4. 批量操作

注意批量接口的数量限制
返回结果包含 successList 和 failList
失败的实例单独处理

5. 网存选择

新项目推荐使用网存2.0
网存2.0实例与存储二合一，更简单
注意存储大小限制

6. 改机属性

修改安卓改机属性后需要重启实例
属性会持久化存储
参考安卓属性列表文档

7. 镜像管理

开机更换镜像仅支持同版本镜像
查询最新预热成功镜像
注意镜像预热状态

8. 错误处理

检查响应 code 字段
记录错误码和错误信息
根据错误码实现重试逻辑

📖 相关文档

完整API文档: OpenAPI_AI.md
签名验证详解: UsageGuide.md
安卓改机属性列表: InstanceAndroidPropList.html
错误码说明: ErrorMsgCode.md

文档版本: v2.0
最后更新: 2026-02-02
根据 OpenAPI_AI_FAST.md 生成