Help Center/ CloudDevice/ API Reference/ APIs/ Instance Usage/ Preparing Instances in Batches

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

View PDF

Preparing Instances in Batches

Function

Prepare instances in batches.

The prerequisite for calling this API is that the tenant has purchased an instance.

After this API is called, the current instance is ready for streaming.

URI

POST /v1/instances/prepare

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Tenant-level token.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
user_id	Yes	String	User ID. The value can contain a maximum of 32 characters.
instance_ids	Yes	Array of strings	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	Response code. The error code specification is KooPhone.API.1001, and the number increases in ascending order.
error_msg	String	Error description.
data	InstanceStatusWrapper object	Status query result.

**Table 4** InstanceStatusWrapper
Parameter	Type	Description
status_list	Array of InstanceStatus objects	Instance status list.

**Table 5** InstanceStatus
Parameter	Type	Description
instance_id	String	Instance ID.
status	Integer	Cloud phone status (0: ready 1: to be restored 2: to be assigned 3: backing up 4: resetting 5: restarting 6: offline 7: replacing 8: restoring from backup upon expiration 9: failed to restore from backup upon expiration 10: maintaining).

Status code: 400

**Table 6** 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.4001: The instance does not exist. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Status code: 500

**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.4001: The instance does not exist. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Example Requests

/v1/instances/prepare

{
  "user_id" : "1008600000104285462",
  "instance_ids" : [ "iRJEVP96", "iRJEVP96" ]
}

Example Responses

Status code: 200

Normal response.

{
  "data" : {
    "status_list" : [ {
      "instance_id" : "a44uhlf7",
      "status" : 0
    }, {
      "instance_id" : "efjy72gs",
      "status" : 1
    } ]
  },
  "error_code" : "0",
  "error_msg" : "ok"
}