Help Center/ CloudDevice/ API Reference/ APIs/ Instance Subscription/ Provisioning an Instance API

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

View PDF

Provisioning an Instance API

Function

Tenants can call this API to generate instances.

This API must be used together with the BatchShowSku API to obtain all available SKUs from the BatchShowSku API. Tenants can select specifications as required.

If you want to directly purchase the product when calling this API, top up your account and select isAutoPay in the subscription parameters.

If automatic payment is not selected, select manual payment from the unpaid orders of your account based on the corresponding order number after the API is called.

URI

POST /v1/instances/create

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-auth-token	Yes	String	User token.
Content-Type	Yes	String	Data format of the request body. The default value is application/json, indicating that the request body is in JSON format.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
os	Yes	String	Image specifications of the instance to be created. This parameter is mandatory in the current scenario. Enumerated value. AOSP9: AOSP9 (image 9) and AOSP11 (image 11).
instanceSkuId	Yes	String	Specification ID of the created instance, which is defined in CBC. The console provides the mapping between the specification and resource pool. The value can contain a maximum of 64 characters.
bandSkuId	Yes	String	Bandwidth product specification ID, which is defined in CBC. This parameter is mandatory for general cloud terminals and cloud applications. The value can contain a maximum of 64 characters.
regionId	Yes	String	Region ID. The value can contain a maximum of 64 characters.
instanceNamePrefix	Yes	String	Prefix of the cloud phone instance name. The value can contain a maximum of 14 characters.
bandSize	Yes	Double	Bandwidth, in Mbit/s.
count	Yes	Integer	Number of instances to be purchased. A maximum of 1500 instances can be purchased.
chargeParam	Yes	chargeParam object	The billing-related parameters.
network	No	String	Network line.

**Table 3** chargeParam
Parameter	Mandatory	Type	Description
chargingMode	Yes	Integer	Billing mode. 1: yearly/monthly. Currently, only the yearly/monthly mode is supported.
periodType	Yes	Integer	Subscription period type. 2: month 3: year
periodNum	Yes	Integer	Number of subscription periods. If the subscription period is a month, the value ranges from 1 to 9. If the subscription period is a year, the value ranges from 1 to 10.
isAutoPay	No	Integer	Automatic payment or not. Automatic payment is disabled by default. 0: automatic payment disabled 1: automatic payment enabled
isAutoRenew	No	Integer	Automatic renew or not. 0: auto-renewal disabled 1: auto-renewal enabled

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
data	data object	Returned content.
error_code	String	0: success
error_msg	String	OK: success

**Table 5** data
Parameter	Type	Description
orderId	String	Order ID.
instanceInfos	Array of instanceInfos objects	Instance information.

**Table 6** instanceInfos
Parameter	Type	Description
instanceId	String	Instance ID.
instanceName	String	Instance name.

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.3001: The instanceSkuId parameter in the request must match the bandSkuId parameter. KOOPHONE.API.3002: The SKU or region does not exist. KOOPHONE.API.3003: The OS image version is required for common instances. KOOPHONE.API.3006: If the period type is month, the value of period num must range from 1 to 9. KOOPHONE.API.3007: If the period type is year, the value of period num must range from 1 to 3. KOOPHONE.API.40010: Insufficient instances. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Example Requests

Subscription request parameters.

/instances/create

{
  "os" : "AOSP9",
  "instanceSkuId" : "kp.professional.2xlarge.128g.2",
  "bandSkuId" : "kp.bandwidth",
  "regionId" : "cn-north-7",
  "instanceNamePrefix" : "koophone",
  "bandSize" : 4,
  "count" : 1,
  "chargeParam" : {
    "chargingMode" : 1,
    "periodType" : 2,
    "periodNum" : 1,
    "isAutoPay" : 1,
    "isAutoRenew" : 1
  },
  "network" : "EIP"
}

Example Responses

Status code: 200

Instance subscription return parameter.

{
  "data" : {
    "orderId" : "CS2412261442DBN4E",
    "instanceInfos" : [ {
      "instanceId" : "11J6QVu5",
      "instanceName" : "koophone-00001"
    } ]
  },
  "error_code" : "0",
  "error_msg" : "OK"
}