VSPHONE OpenAPI 开发者速查手册

供 AI/大模型/代码助手直接读取。完整请求/响应参数与示例见 OpenAPI.md，认证签名见 example.md。

认证方式

HMAC-SHA256 签名验证（必需）

请求头（每个请求必需）：

  • x-date: 请求UTC时间，ISO 8601格式（如 20240301T093700Z）
  • x-host: 接口访问域名（api.vsphone.com）
  • Content-Type: application/json
  • authorization: HMAC-SHA256 签名

签名格式：

HMAC-SHA256 Credential={AccessKey}, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature={Signature}

签名计算步骤及示例见使用指南 example.md

基础信息

  • 域名: https://api.vsphone.com
  • 路径前缀: /vsphone/api/padApi/
  • 响应格式: JSON {code, msg, ts, data}
  • 成功状态码: code=200

API 接口清单

1. 实例管理

方法接口说明参数
POST/vsphone/api/padApi/setWifiList修改实例WIFI属性padCodes[], wifiJsonList[], SSID, BSSID, MAC, IP, gateway, DNS1, DNS2...
POST/vsphone/api/padApi/padDetails实例详情(待上线)padCodes[], padIps[], vmStatus, controlStatus, faultStatus, deviceStatus
POST/vsphone/api/padApi/restart实例重启padCodes[]
POST/vsphone/api/padApi/reset实例重置padCodes[]
POST/vsphone/api/padApi/padProperties查询实例属性padCode
POST/vsphone/api/padApi/batchPadProperties批量查询实例属性padCodes[]
POST/vsphone/api/padApi/updatePadProperties修改实例属性(动态生效)padCodes[], modemPersistPropertiesList[], propertiesName...
POST/vsphone/api/padApi/updatePadAndroidProp修改实例安卓改机属性(需重启)padCode, restart, props, ro.product.vendor.name
POST/vsphone/api/padApi/updateSIM根据国家Code修改SIM卡信息padCode, countryCode, props, ro.product.vendor.name
POST/vsphone/api/padApi/dissolveRoom停止推流padCodes[]
POST/vsphone/api/padApi/checkIP智能IP代理检测host, port, account, password, type, country, ip, loc, city...
POST/vsphone/api/padApi/smartIp设置智能IPpadCodes[], host, port, account, password, type, mode...
POST/vsphone/api/padApi/notSmartIp取消智能IPpadCodes[]
POST/vsphone/api/padApi/getTaskStatus设备任务执行结果查询(智能IP)taskId
POST/vsphone/api/padApi/getListInstalledApp获取指定云机安装的应用信息padCodeList[]
POST/vsphone/api/padApi/updateTimeZone修改实例时区timeZone, padCodes[]
POST/vsphone/api/padApi/updateLanguage修改实例语言language, country, padCodes[]
POST/vsphone/api/padApi/gpsInjectInfo设置实例经纬度longitude, latitude, altitude, speed, bearing...
POST/vsphone/api/padApi/replacePad一键新机padCodes[], countryCode, realPhoneTemplateId, androidProp...
GET/vsphone/api/padApi/country查询一键新机支持国家列表-
POST/vsphone/api/padApi/updateContacts更新通讯录padCodes[], fileUniqueId, operateType, info[]...
POST/vsphone/api/padApi/setProxy实例设置代理account, password, ip, port, enable, padCodes[], proxyType...
POST/vsphone/api/padApi/listInstalledApp实时查询已安装的应用列表padCodes[], appName
POST/vsphone/api/padApi/setKeepAliveApp设置应用自启动padCodes[], applyAllInstances, appInfos[], serverName
POST/vsphone/api/padApi/asyncCmd异步执行ADB命令padCodes[], scriptContent
POST/vsphone/api/padApi/switchRoot开关Root权限padCodes[], globalRoot, packageName, rootStatus
POST/vsphone/api/padApi/screenshot本地截图padCodes[], rotation, broadcast, definition, resolutionHeight...
POST/vsphone/api/padApi/getLongGenerateUrl获取实例实时预览图片padCodes[], format, height, width, quality
POST/vsphone/api/padApi/upgradeImage升级镜像padCodes[], imageId, wipeData, enableCpuCoreConfig
POST/vsphone/api/padApi/virtualRealSwitch升级真机镜像padCodes[], imageId, wipeData, realPhoneTemplateId...
POST/vsphone/api/padApi/templateList分页获取真机模板page, rows
POST/vsphone/api/padApi/openOnlineAdb开启关闭ADBpadCodes[], openStatus
POST/vsphone/api/padApi/adb获取ADB连接信息padCode, enable
POST/vsphone/api/padApi/simulateTouch模拟触控padCodes[], width, height, pointCount, positions[]
POST/vsphone/api/padApi/padTaskDetail实例操作任务详情taskIds[], taskId
POST/vsphone/api/padApi/infos实例分组列表/实例列表信息page, rows, padType, padCodes[]
POST/vsphone/api/padApi/addPhoneRecord导入通话记录padCodes[], callRecords[]
POST/vsphone/api/padApi/inputText云机文本信息输入padCodes[], text, code, msg, ts, data[]...
POST/vsphone/api/padApi/simulateSendSms模拟发送短信padCodes[], senderNumber, smsContent
POST/vsphone/api/padApi/resetGAID重置GAIDpadCodes[], resetGmsType, oprBy, taskSource
POST/vsphone/api/padApi/injectAudioToMic注入音频到实例麦克风padCodes[], url, fileUniqueId, enable
POST/vsphone/api/padApi/addUserRom上传用户镜像name, updateLog, androidVersion, version, downloadUrl, packageSize
POST/vsphone/api/padApi/replacement换机padCode
POST/vsphone/api/padApi/confirmTransfer云机转移padCodes[], makeOverMobilePhone

2. 资源管理

方法接口说明参数
POST/vsphone/api/padApi/infos实例列表信息(分页查询已订购实例)page, rows, padType, padCodes[]

3. 应用管理

方法接口说明参数
POST/vsphone/api/padApi/uninstallApp应用卸载apkPackageList[], padCodeList[]
POST/vsphone/api/padApi/startApp应用启动pkgName, padCodes[]
POST/vsphone/api/padApi/stopApp应用停止pkgName, padCodes[]
POST/vsphone/api/padApi/restartApp应用重启pkgName, padCodes[]
POST/vsphone/api/padApi/listInstalledApp实例安装应用列表查询padCodes[], appName
POST/vsphone/api/padApi/uploadFileV3文件通过链接直接上传padCodes[], padCode, autoInstall, fileUniqueId...
POST/vsphone/api/padApi/uploadFile上传文件到云空间file
POST/vsphone/api/padApi/deleteOssFiles删除云空间文件files[], urls[]
POST/vsphone/api/padApi/selectFiles查询用户的文件列表-

4. 任务管理

方法接口说明参数
POST/vsphone/api/padApi/padTaskDetail实例操作任务详情taskIds[], taskId
POST/vsphone/api/padApi/fileTaskDetail文件任务详情taskIds[], taskId

5. 云手机管理

方法接口说明参数
POST/vsphone/api/padApi/createMoneyOrder新建续费云手机androidVersionName, goodId, goodNum, autoRenew, equipmentId
POST/vsphone/api/padApi/userPadList云手机列表padCode, equipmentIds[]
POST/vsphone/api/padApi/padInfo云手机信息查询padCode
GET/vsphone/api/padApi/getCloudGoodListsku套餐列表androidVersion
POST/vsphone/api/padApi/createMoneyProOrder设备预售购买androidVersionName, goodId, goodNum, autoRenew
POST/vsphone/api/padApi/queryProOrderList查询预售订单结果详情proBuyStatus, orderId
POST/vsphone/api/padApi/imageVersionList安卓镜像版本集合padCode

6. TK 自动化

方法接口说明参数
POST/vsphone/api/padApi/autoTaskList自动化任务列表查询taskIds[], taskType, page, rows
POST/vsphone/api/padApi/addAutoTask创建自动化任务taskName, remarks, taskType, list[]
POST/vsphone/api/padApi/reExecutionAutoTask自动化任务重试taskIds[], plannedExecutionTime
POST/vsphone/api/padApi/cancelAutoTask自动化任务取消taskIds[]

7. SDK Token

方法接口说明参数
GET/vsphone/api/padApi/stsToken获取SDK临时Token-
POST/vsphone/api/padApi/stsTokenByPadCode根据padCode获取SDK临时tokenpadCode
POST/vsphone/api/padApi/clearStsToken清除SDK授权Tokentoken

回调通知事件

事件码说明
999实例状态回调
1000实例重启任务
1001实例重置任务
1002异步执行ADB任务
1003应用安装任务
1004应用卸载任务
1005应用停止任务
1006应用重启任务
1007应用启动任务
1009实例文件上传任务
1012实例升级镜像任务
1124一键新机
4001用户镜像上传

详细字段与示例见 callback.md

常见错误码

错误码说明
200成功
2031无效的密钥
2032请求头缺少Authorization
2019验证签名失败
100000请求参数不正确
100003缺少请求头Authorization
100004无效的签名
100005验证签名失败
110028实例不存在
110013实例不存在
110031实例未就绪
120008token不属于当前用户

更多错误码见 ErrorCode.md

使用建议

  1. 认证安全

    • 妥善保管AK/SK，勿在客户端硬编码
    • 定期更换密钥

  2. 异步任务

    • 重启、重置、安装、上传等为异步任务
    • 建议配置回调或使用任务详情接口轮询结果

  3. 批量限制

    • 批量接口有数量上限（如200个实例）
    • 注意分批与失败列表处理

  4. 实例状态

    • 部分操作要求实例在线或就绪
    • 先查实例状态再调用

  5. 改机与重启

    • 修改安卓改机属性、SIM等需重启生效
    • 与「修改实例属性」的生效时机区别

相关文档

文档版本: 速查版 内容以 OpenAPI.md 为准