All Products
Search

This Product

    Elastic Desktop Service:CreateDesktops

    Document Center

    Elastic Desktop Service:CreateDesktops

    Last Updated:Jul 06, 2026

    Creates one or more cloud desktops. If user information is specified during creation, the cloud desktops are directly assigned to the users.

    Operation description

    Before creating cloud desktops, complete the following preparations:

    Call examples:

    Example of creating with a template

    {
  "RegionId": "ap-southeast-1",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "ap-southeast-1+dir-xxx",// Create an office network in advance
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "BundleId": "b-enterprise_office_8c16g_windows2022"
}

    Example of creating without a template

    {
  "RegionId": "ap-southeast-1",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "ap-southeast-1+dir-xxx",// Create an office network in advance
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "ImageId": "desktopimage-windows-server-2022-64-asp",
    "SystemDiskSize": "40",
    "DataDiskSize": "0",
    "DefaultLanguage": "zh-CN",
    "DesktopType": "eds.enterprise_office.4c8g"
  }
}

    Example of creating a monthly hourly package

    {
  "RegionId": "ap-southeast-1",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "ap-southeast-1+dir-xxx",// Create an office network in advance
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "ImageId": "desktopimage-windows-server-2022-64-asp",
    "SystemDiskSize": "40",
    "DataDiskSize": "0",
    "DefaultLanguage": "zh-CN",
    "DesktopType": "eds.enterprise_office.4c8g"
  },
  "MonthDesktopSetting": {
    "UseDuration": "120"
  },
  "Period": "1",
  "PeriodUnit": "Month"
}

    Example of creating an Agent resource

    {
  "RegionId": "ap-southeast-1",
  "BundleId": "b-openclaw-linux",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "ap-southeast-1+dir-xxx",// Create an office network in advance
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "DesktopType": "cloud.space.4c.8g"
  },
  "PurchaseOptions": {
    "MonthlyCredits": "120"
  },
  "Period": "1",
  "PeriodUnit": "Month"
}

    To have cloud desktops automatically run custom command scripts, use the UserCommands field to configure custom commands.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecd:CreateDesktops

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID. You can call DescribeRegions to query the regions supported by WUYING Workspace.

    cn-hangzhou
    GroupId

    string

    No

    The cloud desktop pool ID.

    dg-boyczi8enfyc5****
    BundleId

    string

    No

    The cloud desktop template ID. If no template ID is specified, you can create a cloud desktop by specifying the required fields.

    b-je9hani001wfn****
    DesktopName

    string

    No

    The cloud desktop name. The naming rules are as follows:

    • The name can be up to 64 characters in length.

    • The name must start with a letter or a Chinese character and cannot start with http:// or https://.

    • The name can contain Chinese characters, letters, digits, colons (:), underscores (_), periods (.), or hyphens (-).

    DemoComputer01
    UserName

    string

    No

    Note

    This parameter is not available for use.

    username
    VpcId

    string

    No

    Note

    This parameter is not available for use.

    vpc-uf6w8u60n8xbkg5el****
    Amount

    integer

    No

    The number of cloud desktops to create. Valid values: 1 to 300. Default value: 1.

    1
    DirectoryId

    string

    No

    Note

    This parameter is not available for use.

    cn-hangzhou+dir-300943****
    OfficeSiteId

    string

    No

    The office network ID.

    cn-hangzhou+dir-387822****
    PolicyGroupId

    string

    No

    The policy ID.

    system-all-enabled-policy
    ChargeType

    string

    No

    The billing method of the cloud desktop.

    Valid values:

    • PostPaid :

      pay-as-you-go [default]

    • PrePaid :

      subscription.

    PrePaid
    Period

    integer

    No

    The subscription duration of the resource. The unit is specified by PeriodUnit. This parameter takes effect and is required only when ChargeType is set to PrePaid.

    • If PeriodUnit is set to Month, valid values of this parameter:

      • 1

      • 2

      • 3

      • 6

    • If PeriodUnit is set to Year, valid values of this parameter:

      • 1

      • 2

      • 3

      • 4

      • 5

    1
    PeriodUnit

    string

    No

    The unit of the subscription duration.

    Valid values:

    • Month :

      month [default]

    • Year :

      year.

    Month
    AutoPay

    boolean

    No

    Specifies whether to enable automatic payment.

    Valid values:

    • true :

      Automatic payment is enabled. Make sure that your account balance is sufficient. Otherwise, abnormal orders are generated. [default]

    • false :

      An order is generated but not paid. You can log on to the console and go to the Orders page in User Center to complete the payment based on the returned order ID.

    false
    AutoRenew

    boolean

    No

    Specifies whether to enable auto-renewal. This parameter takes effect only when ChargeType is set to PrePaid.

    Valid values:

    • true :

      Auto-renewal is enabled. The renewal duration is the same as the subscription duration.

    • false :

      Auto-renewal is disabled. [default]

    false
    PromotionId

    string

    No

    The promotion ID.

    23141
    UserAssignMode

    string

    No

    The cloud desktop assignment mode.

    Note

    If EndUserId is not specified, the created cloud desktops are not assigned to any user.

    Valid values:

    • ALL :

      If EndUserId is specified, the created cloud desktops are assigned to each specified user. [default]

    • PER_USER :

      If EndUserId is specified, the created cloud desktops are evenly distributed among the specified users. The value of Amount must be divisible by the number of EndUserId values (N).

    ALL
    Hostname

    string

    No

    The custom hostname of the cloud desktop. Settings for this parameter are supported only for cloud desktops that run the Windows operating system in an AD office network.

    The naming rules for the hostname are as follows:

    • The hostname must be 2 to 15 characters in length.

    • The hostname can contain uppercase letters, lowercase letters, digits, or hyphens (-). It cannot start or end with a hyphen, contain consecutive hyphens, or consist of only digits.

    When you create multiple cloud desktops, you can use the name_prefix[begin_number,bits]name_suffix format to uniformly name the cloud desktops. For example, if you set Hostname to ecd-[1,4]-test, the hostname of the first cloud desktop is ecd-0001-test, the hostname of the second cloud desktop is ecd-0002-test, and so on.

    • name_prefix: the prefix of the hostname.

    • [begin_number,bits]: the sequential number in the hostname. begin_number is the starting number. Valid values: 0 to 999999. Default value: 0. bits is the number of digits. Valid values: 1 to 6. Default value: 6.

    • name_suffix: the suffix of the hostname.

    testhost
    EndUserId

    array

    No

    The list of authorized user IDs to add to the cloud desktops. You can specify 1 to 100 user IDs.

    123456789

    string

    No

    The authorized user ID to add to the cloud desktop.

    • Only one user can use the cloud desktop at a time.

    • If EndUserId is not specified, the created cloud desktops are not assigned to any user.

    alice
    Tag

    array<object>

    No

    The tags.

    object

    No

    The tags.

    Key

    string

    No

    The tag key. You can specify 1 to 20 tag keys.

    TestKey
    Value

    string

    No

    The tag value. You can specify 1 to 20 tag values.

    TestValue
    DesktopNameSuffix

    boolean

    No

    Specifies whether to automatically append a suffix to the cloud desktop name when you create multiple cloud desktops in a batch.

    Valid values:

    • true :

      A suffix is automatically appended. [default]

    • false :

      No suffix is appended.

    false
    VolumeEncryptionEnabled

    boolean

    No

    Specifies whether to enable cloud disk encryption.

    Valid values:

    • true :

      Cloud disk encryption is enabled.

    • false :

      Cloud disk encryption is disabled. [default]

    false
    VolumeEncryptionKey

    string

    No

    The ID of the Key Management Service (KMS) key used for cloud disk encryption. You can call ListKeys to obtain the key ID.

    08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
    DesktopMemberIp

    string

    No

    The private IP address of the cloud desktop.

    10.0.0.1
    UserCommands

    array<object>

    No

    The custom command script data.

    object

    No

    The custom command script data.

    ContentEncoding

    string

    No

    The encoding method of the command content (CommandContent).

    Valid values:

    • Base64 :

      Base64 encoding.

    • PlainText :

      no encoding, transmitted in plaintext.

    Base64
    Content

    string

    No

    The command content.

    bmV3LWl0ZW0gZDpcdGVzdF91c2VyX2NvbW1hbmRzLnR4dCAtdHlwZSBm****
    ContentType

    string

    No

    The language type of the command.

    Valid values:

    • RunPowerShellScript :

      PowerShell command for Windows instances.

    • RunShellScript :

      Shell command for Linux instances.

    • RunBatScript :

      Bat command for Windows instances.

    RunPowerShellScript
    BundleModels

    array<object>

    No

    The list of cloud desktop templates.

    object

    No

    The cloud desktop template.

    BundleId

    string

    No

    The cloud desktop template ID.

    b-je9hani001wfn****
    Amount

    integer

    No

    The number of cloud desktops to create. Valid values: 1 to 300. Default value: 0.

    1
    EndUserIds

    array

    No

    The list of users to whom the cloud desktops are assigned.

    string

    No

    The username.

    alice
    DesktopName

    string

    No

    The cloud desktop name. The naming rules are as follows:

    • The name can be up to 64 characters in length.

    • The name must start with a letter or a Chinese character and cannot start with http:// or https://.

    • The name can contain Chinese characters, letters, digits, colons (:), underscores (_), periods (.), or hyphens (-).

    DemoComputer02
    Hostname

    string

    No

    The custom hostname of the cloud desktop. Settings for this parameter are supported only for cloud desktops that run the Windows operating system in an AD office network.

    The naming rules for the hostname are as follows:

    • The hostname must be 2 to 15 characters in length.

    • The hostname can contain uppercase letters, lowercase letters, digits, or hyphens (-). It cannot start or end with a hyphen, contain consecutive hyphens, or consist of only digits.

    When you create multiple cloud desktops, you can use the name_prefix[begin_number,bits]name_suffix format to uniformly name the cloud desktops. For example, if you set Hostname to ecd-[1,4]-test, the hostname of the first cloud desktop is ecd-0001-test, the hostname of the second cloud desktop is ecd-0002-test, and so on.

    • name_prefix: the prefix of the hostname.

    • [begin_number,bits]: the sequential number in the hostname. begin_number is the starting number. Valid values: 0 to 999999. Default value: 0. bits is the number of digits. Valid values: 1 to 6. Default value: 6.

    • name_suffix: the suffix of the hostname.

    testhost
    VolumeEncryptionEnabled

    boolean

    No

    Specifies whether to enable cloud disk encryption.

    false
    VolumeEncryptionKey

    string

    No

    The ID of the Key Management Service (KMS) key used for cloud disk encryption. You can call ListKeys to obtain the key ID.

    08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
    DesktopTimers

    array<object>

    No

    The scheduled task details of the cloud desktop. This parameter is being deprecated. Use the TimerGroupId parameter instead.

    object

    No

    The scheduled task details of the cloud desktop.

    TimerType

    string

    No

    The type of the scheduled task.

    NoOperationReboot
    CronExpression

    string

    No

    The cron expression of the scheduled task.

    Important Specify the time in UTC. For example, to schedule a task at 00:00 (UTC+8) every day, set the value to 0 0 16 ? * 1,2,3,4,5,6,7.

    0 40 7 ? * 1,2,3,4,5,6,7
    Interval

    integer

    No

    The time interval, in minutes.

    10
    Enforce

    boolean

    No

    Specifies whether to forcefully execute the task.

    Valid values:

    • true :

      The scheduled task is forcefully executed regardless of the cloud desktop status or connection status.

    • false :

      The task is not forcefully executed.

    true
    ResetType

    string

    No

    The reset type of the cloud desktop.

    Valid values:

    • RESET_TYPE_SYSTEM :

      Resets the system cloud disk.

    • RESET_TYPE_BOTH :

      Resets the system cloud disk and user cloud disk.

    RESET_TYPE_SYSTEM
    OperationType

    string

    No

    The operation type of the scheduled task. Currently, only the disconnection scheduled task is supported.

    Valid values:

    • Hibernate :

      hibernate.

    • Shutdown :

      shut down.

    Shutdown
    AllowClientSetting

    boolean

    No

    Specifies whether to allow end users to configure scheduled tasks.

    true
    SubnetId

    string

    No

    The subnet ID.

    vsw-bp1m*****
    MonthDesktopSetting

    object

    No

    The purchase parameters for the monthly hourly package.

    UseDuration

    integer

    No

    The package option when purchasing a monthly hourly package. Valid values: 120, 250, and 360.

    null
    BuyerId

    integer

    No

    Note

    This field is not available for use.

    null
    DesktopId

    string

    No

    Note

    This field is not available for use.

    null
    SnapshotPolicyId

    string

    No

    The WUYING automatic snapshot policy ID.

    sp-28mp6my0l6zow****
    ResourceGroupId

    string

    No

    The WUYING resource group ID.

    rg-3mtuc28rx95lx****
    DesktopAttachment

    object

    No

    The parameters for creating a cloud desktop without a template. This parameter is invalid when the BundleId parameter is specified.

    ImageId

    string

    No

    The image ID.

    m-39ddhdb0ggzjx*****
    SystemDiskCategory

    string

    No

    The system cloud disk type. The system cloud disk type must be the same as the data cloud disk type. Valid values:

    • cloud_auto: standard SSD ultra cloud disk

    • cloud_essd: ESSD cloud disk

    cloud_auto
    SystemDiskSize

    integer

    No

    The system cloud disk capacity. Valid values: 60 to 500 GiB, in increments of 10 GiB.

    40
    SystemDiskPerLevel

    string

    No

    The performance level (PL) of the ESSD cloud disk. This parameter is required when an ESSD cloud disk is selected. Valid values:

    • PL0

    • PL1

    PL0
    DataDiskSize

    integer

    No

    The user cloud disk capacity. Valid values: 40 to 2040 GiB, in increments of 10 GiB.

    40
    DataDiskCategory

    string

    No

    The data cloud disk type. The system cloud disk type must be the same as the data cloud disk type. Valid values:

    • cloud_auto: standard SSD ultra cloud disk

    • cloud_essd: ESSD cloud disk

    cloud_auto
    DataDiskPerLevel

    string

    No

    The performance level (PL) of the ESSD cloud disk. This parameter is required when an ESSD cloud disk is selected. Valid values:

    • PL0

    • PL1

    PL0
    DefaultLanguage

    string

    No

    The language. Valid values:

    • zh-CN

    • zh-HK

    • en-US

    • ja-JP

    zh-CN
    DesktopType

    string

    No

    The cloud desktop specification. You can call DescribeDesktopTypes to query the supported specification IDs.

    eds.enterprise_office.8c16g
    TimerGroupId

    string

    No

    The scheduled task group ID.

    ccg-0caoeogrk9m5****
    SavingPlanId

    string

    No

    Note

    This field is not available for use.

    spn-26c1b7bcrjcI****
    ResellerOwnerUid

    integer

    No

    The user ID for resource ownership in reseller pattern. This parameter is not required in non-reseller pattern.

    1828644634819902
    ExtendInfo

    string

    No

    The extended information in JSON string format. This parameter is available only for internal customers.

    {}
    AppRuleId

    string

    No

    The application control policy ID.

    bwr-245d4e0e6b7d42f5afa97eb3fbc7e488
    QosRuleId

    string

    No

    The public network rate limiting rule ID.

    qos-52fqmg6kvyro7zu4l
    ChannelCookie

    string

    No

    Note

    This field is not available for use.

    PBKB1QbqEl2tslEuU6gRrLxvCFBU2M%2FVD0Eru6Oo%2FI9LTU3XQhvq3PGMWarE%2BPJdkNvCqT3blqlRSthNy4A%2BJQ%3D%3D
    PurchaseOptions

    object

    No

    The additional parameters for a specific purchase type.

    MonthlyCredits

    integer

    No

    The monthly credit package for purchasing Agent resources. Valid values: 200, 1600, and 4000.

    200
    OuPath

    string

    No

    The OU path. If specified, the cloud desktop is added to the corresponding organizational unit (OU) in Active Directory (AD).

    test.com/wuyingtest/computers
    SubPayType

    string

    No

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    OrderId

    string

    The order ID.

    Note

    This parameter is returned only when the request parameter ChargeType is set to PrePaid.

    123456789
    RequestId

    string

    The request ID.

    1CBAFFAB-B697-4049-A9B1-67E1FC5F****
    DesktopId

    array

    The list of cloud desktop IDs. If multiple cloud desktops are created in a single call, multiple cloud desktop IDs are returned.

    string

    The cloud desktop ID.

    ["ecd-gx2x1dhsmucyy****"]

    Examples

    Success response

    JSON format

    {
  "OrderId": "123456789",
  "RequestId": "1CBAFFAB-B697-4049-A9B1-67E1FC5F****",
  "DesktopId": [
    "[\"ecd-gx2x1dhsmucyy****\"]"
  ]
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidEncryptionKey.Missing Parameter VolumeEncryptionKey is missing. When the disk encryption function is enabled, the encryption key cannot be empty.
    400 InvalidEncryptionKey.NotAuthorized Eds service cannot access the given VolumeEncryptionKey. Unable to access unauthorized encryption keys
    400 InvalidEncryptionKey.NotFound The specified VolumeEncryptionKey is not found. The specified encryption key could not be found
    400 InvalidImageStatus.NotValid The specified image status is not valid. The status of the specified image is unavailable and cannot be created.
    400 InvalidImageVersion.NotSupported The specified image version is no longer supported. The specified image version is no longer supported. Please select another image.
    400 InvalidMemberIp.DesktopAmount The desktop amount need to be 1. When you specify an IP to create a desktop, the number of desktops can only be 1
    400 InvalidPolicyGroup.Status The target policy group is being created. Please try again later.
    400 Protocol.NotAllowed Procotol of the image is not allowed. The protocol type of the image is not supported. Check the image ID.
    400 ExistedHostname The specified hostname is existed on the domain. The specified hostname already exists in the current workspace
    400 HostnameCannotCustomizeForLinux Customizing hostname is not supported for Linux desktop. The custom hostname feature does not support Linux desktops
    400 IncorrectDirectoryStatus Only registered directory can create desktop. Workspace status error, only desktop creation with registered workspace is supported
    400 IncorrectDirectoryType The protocol type of directory and desktop do not match. The protocol types of the specified workspace and the target desktop do not match, please check
    400 InvalidAmount The specified Amount is not a valid value. The specified quantity is illegal
    400 InvalidAmount.NotTimesOfUsers The specified Amount is notmatch EndUserId size. The number of desktops specified is not equal to the number of users to be assigned, please re-specify
    400 InvalidDesktopBundle.NotFound The specified param BundleId is not found. Specified BundleId not found
    400 InvalidDirectoryId.NotFound The specified param DirectoryId is not found. Unable to find workspace ID, please check workspace
    400 InvalidDirectoryType.NotSupported The specified DirectoryType is not supported. Specified
    400 InvalidEncryptionEnabled.Invalid The parameter VolumeEncryptionEnabled is invalid. When specifying the encryption key, you need to turn on the disk encryption function.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.