Help Center/ CloudDevice/ API Reference/ APIs/ Application management/ Installing an App on an Instance

Updated on 2025-10-30 GMT+08:00

View PDF

Installing an App on an Instance

Function

Call this API to install applications in batches on a cloud phone instance. When this API is called, the value of fast_install determines whether the applications are installed in common mode or quick mode.

The API returns the task_id of the current installation task. The task_id has a fixed prefix ZGCA.

You can call the GetTask instance execution task query API to query the execution result based on the returned task ID.

URI

POST /v1/instances/app/install

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-request-id	No	String	Unique ID of a request.
x-Auth-Token	No	String	Tenant-level token.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
fast_install	No	String	Installation type. 0: common installation 1: quick installation
object_name	Yes	String	Name of the application package after installation. A package name can contain a maximum of 100 characters, for example, com.tencent.mm.
file_name	Yes	String	File name (suffix included). The value can contain a maximum of 100 characters, for example, meituan.apk.
object_version	Yes	String	Application version. The value can contain a maximum of 100 characters, for example, 8.0.58.
object_size	Yes	String	Application size. Example: 120 (unit: MB)
biz_type	Yes	String	Installation package type. The value can contain a maximum of 64 characters, for example, apk. Currently, only APK applications can be installed.
content_type	Yes	String	Transmission mode. The value can contain a maximum of 64 characters. 1: OBS. Currently, only OBS download is supported. Example: application/octet-stream
content_md5	Yes	String	Verify the MD5 value of the APK file. This parameter can be left empty. It is optional and can contain a maximum of 200 characters.
install_package_url	Yes	String	OBS download URL of the APK package. The value can contain a maximum of 2000 characters.
instance_id_list	Yes	Array of strings	Cloud phone instance list. A single instance can contain a maximum of 32 characters, and the list can contain a maximum of 100 columns.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
data	RmInstallAppResp object	Application installation result.

**Table 4** RmInstallAppResp
Parameter	Type	Description
data	RmInstallAppDataResult object	Execution results.

**Table 5** RmInstallAppDataResult
Parameter	Type	Description
cmd_jobs	Array of CmdJob objects	Command task.
task_id	String	Task ID.

**Table 6** CmdJob
Parameter	Type	Description
instance_id	String	Instance list.
job_id	String	Asynchronization command task ID.

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KOOPHONE.API.3008: The installation type parameter fast_install in the request is incorrect. KOOPHONE.API.62005: The app package already exists. KOOPHONE.API.62006: The app package size is not a digit. KOOPHONE.API.62006: The app package is too large. KOOPHONE.API.62016: The total size of application packages uploaded by the tenant exceeds the upper limit. KOOPHONE.API.3009: Failed to query the phone ID. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Example Requests

Request parameters for installing an application on an instance.

/v1/instances/app/install

{
  "fast_install" : 1,
  "object_name" : "com.tencent.mm",
  "file_name" : "meituan.apk",
  "object_version" : "8.0.58",
  "object_size" : 120,
  "biz_type" : "apk",
  "content_type" : "application/octet-stream",
  "content_md5" : "fghfg",
  "install_package_url" : "https://obs-kpxa-zg.obs.cn-north-7.ulanqab.huawei.com:443/chp_admin/sh/KooPhone/1943225155684069378/1752229415749-2-com.tencent.mm.apk?AccessKeyId=HSTAZ7UE1341BOE861H2&Expires=1753252931&x-obs-security-token=hQpjbi1ub3J0aC03AQAABElIU1RBWjdVRTEzNDFCT0U4NjFIMo-pbpW_du_lXkPTraoMwCYVql1frNdxH_jI3n5jbQHT6gQxKRmZB9zIy8W11u7BnLAZQnxrX8SDIZQV1jvlf9HQbIdvncUjU4YhVximnMUckrYQEDlTUYjrXKxG9bXYeAHt66g7iODBfCRVLvx1jUkA4thsItjcQ-iPGR20FBi2qbk_AF5iOGT0Ig72UjqIVYo_JTbkDWRiAUr4uludn84f_CgYjTPE025u8A_VO2l4yij3cl4TSRxdNxM2gpS8g3vDWpLCZ2UTYbej5dBzQs-yizVaCZmh-kN3A0JmWIvGpOvkSEhKYyWqAonB5UXzO954oj8Oso2nl2UahCVlUtgkGoxMaufkABN_4odeQOFnTYUyxb01aGD3Sv_UQSA_9Tnmy71Hp3ASq6mxF3xLQfrDzDM9Yk0FkZ4t-DQ5FhfQ22L8bR9ru_bmIS6y9XlPC5gxmLp-2APJpUQMDn703Pyr7us4cc-iTA3MiB_rFywCidsDCnw4uwnBwKzvz9qXNhBrNMyvPHSphqT2TsuGaU_-0x_y8KFBdgnJQXLyM1mQY5I0eFOxA3H8WgOTJCL1oQ76Zkg-KXM7UjS_WWU-TFqSIhL-dauPadneL8kai1BS7bsIsg%3D%3D&Signature=BdSN1CfLprzjlaFUGFfnkU5d7lg%3D",
  "instance_id_list" : [ "XvH39QVW", "Vpp8rC4Y" ]
}

Example Responses

Status code: 200

Returned parameters of the instance installation application.

{
  "data" : {
    "data" : {
      "task_id" : "ZGCAorI8ocwK7U7_t0AfH26P-DjwDw8Yknf4",
      "cmd_jobs" : [ {
        "instance_id" : "XvH39QVW",
        "job_id" : "L0XM9bL0sFoKJo-6BEjFzN6ut2jsoH_1"
      }, {
        "instance_id" : "Vpp8rC4Y",
        "job_id" : "1564567b8bab40f34711234cb80d0123"
      } ]
    }
  },
  "error_code" : "0",
  "error_msg" : "OK"
}