All Products
Search

This Product

    Platform For AI:CreateInstance

    Document Center

    Platform For AI:CreateInstance

    Last Updated:Dec 16, 2025

    Creates a DSW instance.

    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

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request syntax

    POST /api/v2/instances HTTP/1.1

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    body

    object

    No

    The properties of the instance.

    WorkspaceId

    string

    No

    The workspace ID. For more information, see ListWorkspaces.

    40823
    InstanceName

    string

    No

    The instance name. The name must meet the following requirements:

    • It can contain only letters, digits, and underscores (_).

    • It cannot exceed 27 characters in length.

    training_data
    EcsSpec

    string

    No

    The ECS instance type. For more information, see ListEcsSpecs.

    ecs.c6.large
    ImageId

    string

    No

    The image ID. For more information, see ListImages.

    image-05cefd0be2exxxx
    ImageUrl

    string

    No

    The image URL. For more information, see ListImages.

    registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu
    Datasets

    array<object>

    No

    The list of datasets.

    object

    No

    A dataset.

    DatasetId

    string

    No

    The dataset ID. If a dataset is read-only, you cannot use MountAccess to change its permissions to read/write.

    For more information, see ListDatasets. This parameter is mutually exclusive with the Uri parameter.

    d-vsqjvs****rp5l206u
    DatasetVersion

    string

    No

    The version of the dataset. You must also specify DatasetId. If you leave this parameter empty, the default value is v1.

    v1
    Uri

    string

    No

    The URI of the storage service directory for direct mounting. This parameter is mutually exclusive with the DatasetId parameter.

    The URI formats for different storage types are as follows:

    • OSS: oss://bucket-name.oss-cn-shanghai-internal.aliyuncs.com/data/path/

    • NAS: nas://29**d-b12****446.cn-hangzhou.nas.aliyuncs.com/data/path/

    • Extreme NAS: nas://29****123-y**r.cn-hangzhou.extreme.nas.aliyuncs.com/data/path/

    • CPFS: cpfs://cpfs-213****87.cn-wulanchabu/ptc-292*****cbb/exp-290********03e/data/path/

    • AI Computing CPFS: bmcpfs://cpfs-290******foflh-vpc-x****8r.cn-wulanchabu.cpfs.aliyuncs.com/data/path/

    oss://bucket-name.oss-cn-shanghai-internal.aliyuncs.com/data/path/
    MountPath

    string

    No

    The mount path of the dataset.

    /mnt/data
    MountAccess

    string

    No

    The read and write permissions on the mounted dataset. If the dataset is read-only, you cannot change the permissions to read/write.

    Valid values:

    • RW :

      Read/write

    • RO :

      Read-only

    RW
    Options

    string

    No

    Custom mount properties. Currently, only OSS is supported. You cannot specify OptionType when you use this parameter. For more information, see DSW mount configurations.

    { "fs.oss.download.thread.concurrency": "10", "fs.oss.upload.thread.concurrency": "10", "fs.jindo.args": "-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink" }

    OptionType deprecated

    string

    No

    The mount type. You cannot specify Options when you use this parameter. This parameter is deprecated. We recommend that you use the Options parameter instead.

    ReadOnly
    Dynamic

    boolean

    No

    Specifies whether to enable dynamic mounting. The default value is false.

    • This feature is supported only for instances that use general computing resources.

    • Only OSS datasets are supported. The mounted dataset is in read-only mode.

    • The MountPath of a dynamically mounted dataset must be a subdirectory of the dynamic mount root path. The default root path is /mnt/dynamic/. For example, /mnt/dynamic/data1/.

    • Dynamically mounted datasets must be specified after non-dynamically mounted datasets.

    true
    UserVpc

    object

    No

    The UserVpc configuration.

    VpcId

    string

    No

    The VPC ID.

    vpc-xxxxx
    VSwitchId

    string

    No

    The vSwitch ID.

    vsw-xxxxx
    SecurityGroupId

    string

    No

    The security group ID.

    sg-xxxxxx
    ExtendedCIDRs

    array

    No

    The extended CIDR blocks.

    • If the vSwitch ID is not specified, you can leave this parameter empty. The system automatically obtains all CIDR blocks of the VPC.

    • If the vSwitch ID is specified, you must specify this parameter. We recommend that you specify all CIDR blocks of the VPC.

    ["192.168.0.1/24", "192.168.1.1/24"]

    string

    No

    An extended CIDR block.

    "172.16.19.0/24","172.16.2.0/24","172.16.12.0/24"
    DefaultRoute

    string

    No

    The default route. Valid values:

    eth0
    ForwardInfos

    array

    No

    The port forwarding information.

    ForwardInfo

    No

    A list of port forwarding information. You can configure parameters such as the mapped port, gateway ID, and Secure Shell (SSH) public key.

    BandwidthLimit

    BandwidthLimit

    No

    Accessibility

    string

    No

    The visibility of the instance.

    Valid values:

    • PUBLIC :

      Visible to all users in the workspace.

    • PRIVATE :

      Visible only to the instance owner and administrators in the workspace.

    PRIVATE
    EnvironmentVariables

    object

    No

    The environment variables to be injected into the DSW instance.

    Warning The environment variables that you specify here may overwrite the preset system environment variables.

    {userName: "Chris"}

    string

    No

    The user-defined environment variables. After the DSW instance starts, the specified environment variables are injected into the container.

    MAAS
    ResourceId

    string

    No

    The resource group ID. This parameter is configured for subscription instances. For more information, see Prepare and manage a DLC resource group cluster.

    dsw-123456789
    Priority

    integer

    No

    The priority. When resources are allocated to instances, instances with higher priorities are given precedence. The value must be an integer from 1 to 9.

    • 1 is the lowest priority.

    • 9 is the highest priority.

    1
    RequestedResource

    object

    No

    The resource configuration.

    {"CPU":"4","Memory":"8Gi","SharedMemory":"4Gi","GPU":"1","GPUType":"Tesla-V100-16G"}
    CPU

    string

    No

    The number of CPU cores.

    32
    Memory

    string

    No

    The memory size, in GiB.

    Important When you pass this parameter, specify the unit. For example, enter 8Gi instead of 8. If you do not specify a unit, MiB is used by default.

    32GB
    SharedMemory

    string

    No

    The shared memory size, in GiB.

    Important When you pass this parameter, specify the unit. For example, enter 4Gi instead of 4. If you do not specify a unit, MiB is used by default.

    32GB
    GPU

    string

    No

    The number of GPUs.

    4
    GPUType

    string

    No

    The GPU card type. Valid values:

    • V100

    • A100

    • T4

    • A10

    • P100

    v100
    Labels

    array<object>

    No

    The custom labels.

    {'foo': 'bar'}

    object

    No

    A custom label.

    Key

    string

    No

    The key of the custom label.

    stsTokenOwner
    Value

    string

    No

    The value of the custom label.

    123xxxxxxxx
    CloudDisks

    array<object>

    No

    The list of disks.

    []

    array<object>

    No

    A list of disks.

    Capacity

    string

    No

    If you set Resource Type to Public Resources, or if you select a subscription general computing resource quota (with at least 2 CPU cores and 4 GB of memory, or with a GPU):

    Each instance is provided with a 100 GiB system disk for free for persistent storage. If the instance is stopped for more than 15 days, the content on the disk is deleted. You can scale out the disk. The pricing for the scale-out is subject to the information on the console page.

    Warning

    • You cannot scale in the disk after it is scaled out. Scale out the disk as needed.

    • After the scale-out, the entire system disk (including the free and paid parts) is no longer subject to the 15-day stop-and-release limit, but fees are continuously incurred.

    • When the instance is deleted, the system disk is also released. Before deleting the instance, make sure that you have backed up the necessary data.

    For persistent storage, configure dataset mounting or add an OSS, NAS, or CPFS path for storage path mounting.

    100Gi
    SubType

    string

    No

    The disk type:

    • rootfs: The disk is mounted as a system disk. The system environment is stored on the disk.

    rootfs
    MountPath

    string

    No

    The mount path of the disk.

    /mnt/systemDisk
    Path

    string

    No

    The subpath of the disk that is mounted to the instance.

    workspace
    Status

    object

    No

    The usage of the disk or snapshot.

    Available

    integer

    No

    The available space in bytes.

    31841058816
    Usage

    integer

    No

    The used space in bytes.

    371195904
    Capacity

    integer

    No

    The total capacity in bytes.

    32212254720
    WorkspaceSource

    string

    No

    Specifies the storage for the working directory. You can mount a disk or a dataset from Datasets to the /mnt/workspace working directory. OSS datasets and dynamically mounted datasets are not supported.

    Specify one of the following values:

    • rootfsCloudDisk: Mounts the disk to the working directory.

    • The mount path of a dataset: The MountPath of a dataset in Datasets, such as /mnt/data. For datasets in URI format, you can only specify the working directory in this way.

    • The ID of a dataset, such as d-vsqjvs****rp5l206u. If the same dataset is mounted to multiple paths, the first path is selected. We recommend that you use the mount path instead of the dataset ID.

    If this parameter is empty:

    • If the instance uses a disk, the disk is selected by default.

    • If no disk is used, the first NAS or CPFS dataset is selected as the working directory.

    • If no disk is used and no NAS or CPFS working directory is available, the host space is used.

    rootfsCloudDisk
    UserId

    string

    No

    The ID of the account that owns the instance. The account can be an Alibaba Cloud account or a RAM user.

    161228528250****
    Driver

    string

    No

    The NVIDIA driver configuration.

    535.54.03
    CredentialConfig CredentialConfig

    No

    The credential configuration.

    Affinity

    object

    No

    The affinity configuration information.

    CPU

    object

    No

    The CPU affinity configuration information. This feature is supported only for subscription instances that use general computing resources.

    Enable

    boolean

    No

    Specifies whether to enable CPU affinity.

    • false: Disables CPU affinity.

    • true: Enables CPU affinity.

    true
    ImageAuth

    string

    No

    The username and password information for the user's private image, which is Base64-encoded. The password is hidden.

    ****
    DynamicMount DynamicMount

    No

    The dynamic mount configuration.

    Tag

    array<object>

    No

    The list of tags.

    object

    No

    A tag.

    Key

    string

    No

    The key of the tag.

    tag1
    Value

    string

    No

    The value of the tag.

    value1
    UserCommand

    object

    No

    The user-defined commands.

    OnStart

    object

    No

    The custom command that is executed every time the instance starts. The command is executed after the instance environment is initialized and before services such as jupyter-lab and code-server start.

    Content

    string

    No

    The content of the custom startup command.

    OversoldType

    string

    No

    The type of preemptible resources. Valid values: `ForceQuotaOverSold`: Use only preemptible resources. `AcceptQuotaOverSold`: Accept preemptible resources. `ForbiddenQuotaOverSold`: Use guaranteed resources.

    AssignNodeSpec

    object

    No

    The node scheduling configuration.

    NodeNames

    string

    No

    The nodes to which the instance is scheduled. Example: "node-a,node-b".

    node-a
    AntiAffinityNodeNames

    string

    No

    The nodes that are excluded from scheduling. Example: "node-a,node-b".

    node-b
    SpotSpec

    object

    No

    The configuration of the spot instance.

    SpotStrategy

    string

    No

    The preemption strategy. Valid values: `SpotWithPriceLimit`: Set a custom maximum hourly price for the spot instance. `SpotAsPriceGo`: The system automatically bids based on the real-time market price.

    SpotWithPriceLimit
    SpotPriceLimit

    string

    No

    The maximum hourly price for the spot instance. The value can be accurate to three decimal places. This parameter is required when SpotStrategy is set to SpotWithPriceLimit.

    0.12
    SpotDuration

    string

    No

    The protection period of the spot instance. The default value is 1. You can set the value to 0 to indicate that no protection period is provided. This parameter is not valid for Lingjun specifications.

    0
    SpotDiscountLimit

    string

    No

    The maximum hourly discount for the spot instance. This parameter is required for Lingjun specifications.

    0.1
    MigrationOptions

    object

    No

    Response elements

    Element

    Type

    Description

    Example

    object

    The result of the operation.

    RequestId

    string

    The request ID.

    E7D55162-4489-1619-AAF5-3F97D5FCA948
    Success

    boolean

    Indicates whether the request was successful. Valid values:

    • true

    • false

    true
    Message

    string

    The description of the returned result.

    "XXX"
    Code

    string

    The status code. Valid values:

    • InternalError: An internal error occurred. All errors except parameter validation errors are classified as internal errors.

    • ValidationError: A parameter validation error occurred.

    null
    HttpStatusCode

    integer

    The HTTP status code. Valid values:

    • 400

    • 404

    • 200

    200
    InstanceId

    string

    The instance ID.

    dsw-730xxxxxxxxxx

    Examples

    Success response

    JSON format

    {
  "RequestId": "E7D55162-4489-1619-AAF5-3F97D5FCA948",
  "Success": true,
  "Message": "\"XXX\"",
  "Code": "null",
  "HttpStatusCode": 200,
  "InstanceId": "dsw-730xxxxxxxxxx"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.