VSPhone OpenAPI Developer Quick Reference

For AI/LLM/code assistants. Full request/response params and examples see OpenAPI.md, auth and signing see example.md.

Authentication

HMAC-SHA256 signature verification (required)

Request headers (required per request):

  • x-date: Request UTC time, ISO 8601 format (e.g. 20240301T093700Z)
  • x-host: API host (api.vsphone.com)
  • Content-Type: application/json
  • authorization: HMAC-SHA256 signature

Signature format:

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

Signature steps and examples see Getting Started example.md

Base Information

  • Base URL: https://api.vsphone.com
  • Path prefix: /vsphone/api/padApi/
  • Response format: JSON {code, msg, ts, data}
  • Success code: code=200

API List

1. Instance Management

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/setWifiListModify instance WIFI propertiespadCodes[], wifiJsonList[], SSID, BSSID, MAC, IP, gateway, DNS1, DNS2...
POST/vsphone/api/padApi/padDetailsInstance details (pending)padCodes[], padIps[], vmStatus, controlStatus, faultStatus, deviceStatus
POST/vsphone/api/padApi/restartInstance restartpadCodes[]
POST/vsphone/api/padApi/resetInstance resetpadCodes[]
POST/vsphone/api/padApi/padPropertiesQuery instance propertiespadCode
POST/vsphone/api/padApi/batchPadPropertiesBatch query instance propertiespadCodes[]
POST/vsphone/api/padApi/updatePadPropertiesModify instance properties (dynamic)padCodes[], modemPersistPropertiesList[], propertiesName...
POST/vsphone/api/padApi/updatePadAndroidPropModify instance Android modification props (restart required)padCode, restart, props, ro.product.vendor.name
POST/vsphone/api/padApi/updateSIMModify SIM by country codepadCode, countryCode, props, ro.product.vendor.name
POST/vsphone/api/padApi/dissolveRoomStop streamingpadCodes[]
POST/vsphone/api/padApi/checkIPSmart IP proxy detectionhost, port, account, password, type, country, ip, loc, city...
POST/vsphone/api/padApi/smartIpSet smart IPpadCodes[], host, port, account, password, type, mode...
POST/vsphone/api/padApi/notSmartIpCancel smart IPpadCodes[]
POST/vsphone/api/padApi/getTaskStatusDevice task result query (smart IP)taskId
POST/vsphone/api/padApi/getListInstalledAppGet installed apps for specified instancespadCodeList[]
POST/vsphone/api/padApi/updateTimeZoneModify instance timezonetimeZone, padCodes[]
POST/vsphone/api/padApi/updateLanguageModify instance languagelanguage, country, padCodes[]
POST/vsphone/api/padApi/gpsInjectInfoSet instance GPSlongitude, latitude, altitude, speed, bearing...
POST/vsphone/api/padApi/replacePadOne-key new devicepadCodes[], countryCode, realPhoneTemplateId, androidProp...
GET/vsphone/api/padApi/countryQuery one-key new device supported countries-
POST/vsphone/api/padApi/updateContactsUpdate contactspadCodes[], fileUniqueId, operateType, info[]...
POST/vsphone/api/padApi/setProxySet instance proxyaccount, password, ip, port, enable, padCodes[], proxyType...
POST/vsphone/api/padApi/listInstalledAppReal-time query installed app listpadCodes[], appName
POST/vsphone/api/padApi/setKeepAliveAppSet app keep-alivepadCodes[], applyAllInstances, appInfos[], serverName
POST/vsphone/api/padApi/asyncCmdAsync execute ADB commandpadCodes[], scriptContent
POST/vsphone/api/padApi/switchRootSwitch Root permissionpadCodes[], globalRoot, packageName, rootStatus
POST/vsphone/api/padApi/screenshotLocal screenshotpadCodes[], rotation, broadcast, definition, resolutionHeight...
POST/vsphone/api/padApi/getLongGenerateUrlGet instance real-time preview imagepadCodes[], format, height, width, quality
POST/vsphone/api/padApi/upgradeImageUpgrade imagepadCodes[], imageId, wipeData, enableCpuCoreConfig
POST/vsphone/api/padApi/virtualRealSwitchUpgrade real device imagepadCodes[], imageId, wipeData, realPhoneTemplateId...
POST/vsphone/api/padApi/templateListPaginated get real device templatespage, rows
POST/vsphone/api/padApi/openOnlineAdbEnable/disable ADBpadCodes[], openStatus
POST/vsphone/api/padApi/adbGet ADB connection infopadCode, enable
POST/vsphone/api/padApi/simulateTouchSimulate touchpadCodes[], width, height, pointCount, positions[]
POST/vsphone/api/padApi/padTaskDetailInstance operation task detailstaskIds[], taskId
POST/vsphone/api/padApi/infosInstance group list / instance list infopage, rows, padType, padCodes[]
POST/vsphone/api/padApi/addPhoneRecordImport call recordspadCodes[], callRecords[]
POST/vsphone/api/padApi/inputTextCloud phone text inputpadCodes[], text, code, msg, ts, data[]...
POST/vsphone/api/padApi/simulateSendSmsSimulate send SMSpadCodes[], senderNumber, smsContent
POST/vsphone/api/padApi/resetGAIDReset GAIDpadCodes[], resetGmsType, oprBy, taskSource
POST/vsphone/api/padApi/injectAudioToMicInject audio to instance microphonepadCodes[], url, fileUniqueId, enable
POST/vsphone/api/padApi/addUserRomUpload user imagename, updateLog, androidVersion, version, downloadUrl, packageSize
POST/vsphone/api/padApi/replacementDevice replacementpadCode
POST/vsphone/api/padApi/confirmTransferTransfer cloud phonepadCodes[], makeOverMobilePhone

2. Resource Management

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/infosInstance list info (paginated query ordered instances)page, rows, padType, padCodes[]

3. Application Management

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/uninstallAppUninstall appapkPackageList[], padCodeList[]
POST/vsphone/api/padApi/startAppStart apppkgName, padCodes[]
POST/vsphone/api/padApi/stopAppStop apppkgName, padCodes[]
POST/vsphone/api/padApi/restartAppRestart apppkgName, padCodes[]
POST/vsphone/api/padApi/listInstalledAppInstance installed app list querypadCodes[], appName
POST/vsphone/api/padApi/uploadFileV3Upload file via URLpadCodes[], padCode, autoInstall, fileUniqueId...
POST/vsphone/api/padApi/uploadFileUpload file to cloud storagefile
POST/vsphone/api/padApi/deleteOssFilesDelete cloud storage filesfiles[], urls[]
POST/vsphone/api/padApi/selectFilesQuery user file list-

4. Task Management

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/padTaskDetailInstance operation task detailstaskIds[], taskId
POST/vsphone/api/padApi/fileTaskDetailFile task detailstaskIds[], taskId

5. Cloud Phone Management

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/createMoneyOrderCreate/renew cloud phoneandroidVersionName, goodId, goodNum, autoRenew, equipmentId
POST/vsphone/api/padApi/userPadListCloud phone listpadCode, equipmentIds[]
POST/vsphone/api/padApi/padInfoCloud phone info querypadCode
GET/vsphone/api/padApi/getCloudGoodListSKU package listandroidVersion
POST/vsphone/api/padApi/createMoneyProOrderDevice presale purchaseandroidVersionName, goodId, goodNum, autoRenew
POST/vsphone/api/padApi/queryProOrderListQuery presale order result detailsproBuyStatus, orderId
POST/vsphone/api/padApi/imageVersionListAndroid image version listpadCode

6. TK Automation

MethodEndpointDescriptionParameters
POST/vsphone/api/padApi/autoTaskListAutomation task list querytaskIds[], taskType, page, rows
POST/vsphone/api/padApi/addAutoTaskCreate automation tasktaskName, remarks, taskType, list[]
POST/vsphone/api/padApi/reExecutionAutoTaskAutomation task retrytaskIds[], plannedExecutionTime
POST/vsphone/api/padApi/cancelAutoTaskAutomation task canceltaskIds[]

7. SDK Token

MethodEndpointDescriptionParameters
GET/vsphone/api/padApi/stsTokenGet SDK temporary token-
POST/vsphone/api/padApi/stsTokenByPadCodeGet SDK temporary token by padCodepadCode
POST/vsphone/api/padApi/clearStsTokenClear SDK authorization tokentoken

Callback Events

Event CodeDescription
999Instance status callback
1000Instance restart task
1001Instance reset task
1002Async ADB task
1003App install task
1004App uninstall task
1005App stop task
1006App restart task
1007App start task
1009Instance file upload task
1012Instance upgrade image task
1124One-key new device
4001User image upload

Details and examples see callback.md

Common Error Codes

Error CodeDescription
200Success
2031Invalid key
2032Missing Authorization header
2019Signature verification failed
100000Invalid request parameters
100003Missing Authorization header
100004Invalid signature
100005Signature verification failed
110028Instance not found
110013Instance not found
110031Instance not ready
120008Token not owned by current user

More error codes see ErrorCode.md

Usage Tips

  1. Auth security

    • Keep AK/SK secure, do not hardcode in client
    • Rotate keys periodically

  2. Async tasks

    • Restart, reset, install, upload etc. are async
    • Configure callback or poll task detail API for result

  3. Batch limits

    • Batch APIs have limits (e.g. 200 instances)
    • Batch requests and handle failure list

  4. Instance state

    • Some operations require instance online/ready
    • Check instance state before calling

  5. Modification props and restart

    • Modifying Android modification props, SIM etc. requires restart
    • Differs from "modify instance properties" (dynamic)

Doc version: Quick reference Content subject to OpenAPI.md