Help Center/ Workspace/ API Reference/ Workspace APIs/ Desktop/ Creates a desktop

Updated on 2026-02-10 GMT+08:00

View PDF

Creates a desktop

Function

Creates and assigns a desktop to a user. After the desktop is created, the user can log in to the desktop.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
workspace:desktops:create	Write	desktop *	-	-	ims:images:get ims:images:list ims:images:share ims:images:updateMemberStatus ims:images:deleteMember ims:images:addMember vpc:networks:get vpc:ports:create vpc:ports:delete vpc:ports:get vpc:ports:update eip:publicIps:get eip:publicIps:list eip:publicIps:create eip:publicIps:associateInstance eip:publicIps:delete eip:publicIps:createTags vpc:quotas:list vpc:securityGroups:get vpc:subnets:get vpc:vpcs:get dss:pools:list kms:cmk:createGrant kms:cmk:listGrants kms:cmk:get kms:cmk:list
workspace:desktops:create	Write	-	g:RequestTag/<tag-key> g:TagKeys g:EnterpriseProjectId workspace:AssociatePublicIp workspace:AccessMode	-

URI

POST /v2/{project_id}/desktops

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
desktop_type	Yes	String	Specifies the cloud desktop type. DEDICATED: dedicated desktop for a single user. SHARED: Multiple users share the desktop.
availability_zone	No	String	AZ. Desktops are created in the specified AZ.
product_id	Yes	String	Package ID.
buy_type	No	String	Purchase option on the console. The default value is custom. speed: quick purchase custom: custom purchase
image_type	Yes	String	Image type. The default value is private. private: a private image gold: a public image
image_id	Yes	String	Image ID. This parameter is used together with product_id for creating desktops using custom images.
root_volume	Yes	Volume object	System disk.
data_volumes	No	Array of Volume objects	Data disks.
nics	No	Array of Nic objects	Information about the NIC corresponding to the desktop. If this parameter is not specified, the default NIC is used.
security_groups	No	Array of SecurityGroupIdInfo objects	Security group used by the desktop. If no security group is specified, the security group specified in the desktop agent is used by default.
desktops	No	Array of Desktop objects	List of parameters used for creating a desktop. The value contains 1 to 100 characters.
desktop_name	No	String	This parameter is used together with size. If size is set to 1, this parameter indicates the desktop name, which consists of 1 to 15 characters. If size is set to a value greater than 1, this parameter indicates the desktop name prefix, which consists of 1 to 13 characters.
desktop_ips	No	Array of strings	IP addresses assigned to the desktop. The value ranges from 0 to 100.
size	No	Integer	Number of desktops that are not assigned to users. This parameter cannot be used together with desktops. It is used together with desktop_name.
email_notification	No	Boolean	Whether to send an email to notify the desktop user after a desktop is created. The default value is true.
enterprise_project_id	No	String	Enterprise project ID, which is 0 by default.
tags	No	Array of Tag objects	Tag list.
apply_shared_vpc_dedicated_param	No	ApplySharedVpcDedicatedParam object	Input parameter of the shared VPC Direct Connect.
eip	No	Eip object	EIP information.
desktop_name_policy_id	No	String	Policy ID, which is used to specify the desktop name generation policy. If a desktop name is specified, the specified desktop name is used preferentially.
hour_package_product_id	No	String	Hourly desktop package ID.
hour_package_offering_id	No	String	Offering ID of an hourly desktop package.
if_mount_old_desktop_disk	No	Boolean	Whether to mount the disk of the old desktop as a data disk when a new desktop is provisioned.

**Table 3** Volume
Parameter	Mandatory	Type	Description
type	Yes	String	Desktop data disk type, which must be the same as the disk type provided by the system. SAS: high I/O SSD: ultra-high I/O GPSSD: general-purpose SSD
size	Yes	Integer	Disk capacity in GB. The system disk size ranges from 80 to 32760, and the data disk size ranges from 10 to 32760. The value must be a multiple of 10.
iops	No	Integer	Number of read/write operations performed by an EVS disk per second.
throughput	No	Integer	Amount of data read from and written to an EVS disk per second.
kms_id	No	String	KMS key ID, which is used to encrypt the created disk.

**Table 4** Nic
Parameter	Mandatory	Type	Description
subnet_id	Yes	String	ID of the subnet on which the NIC works.

**Table 5** SecurityGroupIdInfo
Parameter	Mandatory	Type	Description
id	Yes	String	Security group ID.

**Table 6** Desktop
Parameter	Mandatory	Type	Description
user_name	Yes	String	User to whom a desktop belongs. After a desktop is created, the user can log in to the desktop. Only letters, digits, hyphens (-), and underscores (_) are allowed. When the domain type is LITE_AD, the value contains 1 to 20 characters starting with a letter. When the domain type is LOCAL_AD, the value contains 1 to 32 characters starting with a letter or digit. A Windows desktop username can contain a maximum of 20 characters, and a Linux desktop username can contain a maximum of 32 characters.
domain	No	String	Domain to which the user belongs.
user_email	No	String	Valid user email. After a desktop is created, the system informs users through emails.
user_phone	No	String	Mobile number of a valid user.
user_group	No	String	User group to which the desktop user belongs. sudo: Linux administrator group. default: Default Linux user group. administrators: Windows administrator group. Administrators have full access to the desktop and can make any required changes except for forbidden operations. users: standard Windows user group. Standard users can use most software programs and change system settings that do not affect other users.
computer_name	No	String	Desktop name, which must be unique. The desktop name can contain 1 to 15 characters in letters, digits, and hyphens (-). It must start with a letter or digit and cannot end with a hyphen (-).
os_host_name	No	String	Computer name in the OS.
desktop_name_prefix	No	String	Desktop name prefix. This parameter takes effect when computer_name is not specified.
copy_volume_desktop_id	No	String	ID of the desktop whose data disk needs to be copied. If this parameter is specified, copy_volume_ids cannot be empty.
copy_volume_ids	No	Array of strings	List of IDs of the data disks that need to be copied. If this parameter is specified, copy_volume_desktop_id cannot be empty, and the disks must belong to the desktop.
if_delete_old_desktop	No	Boolean	Whether to delete the old desktop that is billed on a pay-per-use basis. If this parameter is set to true, the old desktop is deleted after the new desktop is provisioned and the disk is copied.

**Table 7** Tag
Parameter	Mandatory	Type	Description
key	Yes	String	Specifies the tag key. This parameter cannot be left blank and can contain a maximum of 128 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,\|/.
value	No	String	Value of a tag, which can contain a maximum of 43 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,\|/.

**Table 8** ApplySharedVpcDedicatedParam
Parameter	Mandatory	Type	Description
address	No	String	Shared VPC Direct Connect address specified by the tenant.
port	No	Integer	Shared VPC Direct Connect address port specified by the tenant.
availability_zone	No	Array of strings	AZ used for subscribing to service resources. By default, two AZs are randomly used.

**Table 9** Eip
Parameter	Mandatory	Type	Description
id	No	String	ID of the EIP bound to the desktop. If this parameter is specified, the EIP is preferentially bound.
type	No	String	EIP type.
charge_mode	No	String	EIP bandwidth billing mode. TRAFFIC: billed by traffic. BANDWIDTH: billed by bandwidth.
bandwidth_size	No	Integer	Bandwidth size.

Response Parameters

Status code: 200

**Table 10** Response body parameters
Parameter	Type	Description
job_id	String	ID of the cloud desktop creation task.

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 401

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 403

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 404

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Example Requests

POST /v2/29dfe82ada564ac2b927e1ff036d9a9b/desktops

{
  "desktop_type" : "DEDICATED",
  "image_type" : "gold",
  "image_id" : "a866298d-67db-44b0-a1f1-9d09bdddc20f",
  "root_volume" : {
    "type" : "SAS",
    "size" : 80
  },
  "availability_zone" : "az3.manage.x86",
  "desktops" : [ {
    "user_name" : "ljh-002",
    "user_group" : "administrators",
    "user_email" : "aaaaa@huawei.com"
  } ],
  "nics" : [ {
    "subnet_id" : "5dee0216-2260-47c2-9368-98a27d910e55"
  } ],
  "product_id" : "workspace.c2.large.windows.2",
  "email_notification" : true
}

Example Responses

Status code: 200

Response to the request for creating a cloud desktop.

{
  "job_id" : "3979904c-7beb-4f34-835f-2fa989a5550a"
}

Status Codes

Status Code	Description
200	Response to the request for creating a cloud desktop.
400	The request cannot be understood by the server due to malformed syntax.
401	Authentication failed.
403	No operation permissions.
404	No resources found.
500	An internal service error occurred. For details about the error code, see the error code description.