Updated on 2025-08-20 GMT+08:00

Creating a Notebook Instance

Function

This API is used to create a notebook instance based on specified parameters.

This API applies to the following scenario: When you need to create a notebook instance for a specific task or project, you can use this API to specify the instance specifications, AI engine images, and storage configurations. Before using this API, ensure that you have logged in to the system, have the permission to create a notebook instance, and provide valid creation parameters. After this API is called, the system asynchronously creates a notebook instance. You can obtain the instance status by calling the query API. After the notebook instance is created, you can access the notebook instance through the web page or SSH client. If you do not have the permission to create an instance or the parameters are invalid, the API will return an error message. Other exceptions include insufficient system resources and creation failure. The API will return the corresponding error message.

Constraints

No constraints

Debugging

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

URI

POST /v1/{project_id}/notebooks

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition: Project ID. For details, see Obtaining a Project ID and Name.

Constraints: N/A

Range: N/A

Default Value: N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

description

No

String

Definition: Instance description.

Constraints: N/A

Range: The value can contain up to 512 characters and cannot contain these special characters (&<>"'/).

Default Value: N/A

duration

No

Long

Definition: Running duration calculated from the current time, in milliseconds. The instance automatically stops when the duration expires. It is recommended that this parameter be set in leaseReq. If this parameter is set here, the value set in leaseReq is ignored and the instance is stopped as scheduled.

Constraints: N/A

Range: 3600000 to 259200000

Default Value: 3600000

endpoints

No

Array of EndpointsReq objects

Definition: Only a local IDE (such as PyCharm or VS Code) or SSH client can be used to access a notebook instance.

Constraints: Configurations are only required for remotely accessing a notebook instance via SSH on a local IDE (such as PyCharm or VS Code) or SSH client.

feature

No

String

Definition: Instance type.

Constraints: N/A

Range:

  • DEFAULT: free CodeLab instance. Each user can create only one.

  • NOTEBOOK: billed instance.

Default Value: NOTEBOOK

flavor

Yes

String

Definition: Instance flavor. The following flavors are for reference only. Obtain the flavors displayed on the console in the target region.

  • modelarts.vm.cpu.2u: General-purpose Intel CPU flavor, ideal for rapid data exploration and experiments

  • modelarts.vm.cpu.8u: General computing-plus Intel CPU flavors, ideal for compute-intensive applications

Constraints: N/A

Range: N/A

Default Value: N/A

image_id

Yes

String

Definition: ID of the image used for creating notebook instances. The ID is in the format of a Universally Unique Identifier (UUID). For details, see Querying Supported Images.

Constraints: N/A

Range: Valid image IDs obtained by calling the API for Querying Supported Images.

Default Value: N/A

name

Yes

String

Definition: Instance name.

Constraints: N/A

Range: The value can contain a maximum of 128 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. The name can be duplicate.

Default Value: N/A

pool_id

No

String

Definition: ID of a dedicated resource pool. This parameter is mandatory if a dedicated resource pool is used to create an instance. The dedicated resource pool ID can be obtained by calling the API for [Obtaining Resource Pools] (https://support.huaweicloud.com/intl/en-us/api-modelarts/ListPools.html).

Constraints: N/A

Range: Valid resource pool IDs obtained by calling the API for querying the resource pool list (https://support.huaweicloud.com/intl/en-us/api-modelarts/ListPools.html)

Default Value: N/A

volume

Yes

VolumeReq object

Definition: Storage configuration.

Constraints: N/A

workspace_id

No

String

Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value.

Constraints: N/A

Range: This value is a string of 0 or 32 characters. Only digits or lowercase letters are allowed.

Default Value: 0

hooks

No

CustomHooks object

Definition: Hook configuration of a custom boot script.

Constraints: N/A

lease

No

LeaseReq object

Definition: Instance lease configuration.

Constraints: N/A

Table 3 EndpointsReq

Parameter

Mandatory

Type

Description

allowed_access_ips

No

Array of strings

Definition: Public IP addresses that can remotely access the notebook instance. A maximum of five public IP addresses are supported.

Constraints: N/A

service

No

String

Definition: Supported services.

Constraints: N/A

Range:

  • NOTEBOOK: You can access notebook instances using HTTPS.

  • SSH: You can remotely access notebook instances through SSH.

Default Value: N/A

key_pair_names

No

Array of strings

Definition: Name of the SSH key pair, which can be created and viewed on the Key Pair page of the Elastic Cloud Server (ECS) console.

Constraints: N/A

Table 4 VolumeReq

Parameter

Mandatory

Type

Description

capacity

No

Integer

Definition: Storage capacity, in GB.

Constraints: This attribute takes effect when category is set to EVS.

Range: 5 to 4096

Default Value: 5

category

Yes

String

Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron.

Constraints: N/A

Range:

  • SFS

  • EVS

  • OBS

  • OBSFS: parallel file system

  • EFS: SFS Turbo

Default Value: EVS

ownership

Yes

String

Definition: Resource owner.

Constraints: N/A

Range:

  • MANAGED: Resources are managed by the service.

  • DEDICATED: Resources are managed by the user account. This mode is supported only when the instance category is EFS.

Default Value: N/A

uri

No

String

Definition: URI of the EFS dedicated storage disk or path of the OBS parallel file system. Perform the following steps:

  • EFS: Log in to the SFS console. In the file system list, click the file system name to go to the file system details page. The shared path is the value of this parameter.

  • OBS: The parallel file system name is in the format of obs://< bucket-name>/[/topic/body/section/table/tgroup/tbody/row/entry/ul/li/p/b/br {""}) (br]/. Log in to the OBS console. In the parallel file system list, the file system name is the bucket name. Click the file system name to access its details page. Select a specific directory and choose More > Copy Path on the right. The path is the directory path.

Constraints: This parameter is mandatory only when category is set to EFS, OBS, or OBSFS and ownership is set to DEDICATED.

Range: N/A

Default Value: N/A

id

No

String

Disk ID of the EFS. This parameter is mandatory only when the instance category is EFS and the ownership is DEDICATED. This parameter is mandatory.

To obtain the parameter value, log in to the SFS console. In the file system list, click the file system name to go to the file system details page. ID is the value of this parameter.

Table 5 CustomHooks

Parameter

Mandatory

Type

Description

container_hooks

No

ContainerHooks object

Definition: Container hook configuration.

Constraints: N/A

Table 6 ContainerHooks

Parameter

Mandatory

Type

Description

post_start

No

Config object

Definition: Script configuration after the service is started.

Constraints: N/A

pre_start

No

Config object

Definition: Script configuration before the service is started.

Constraints: N/A

Table 7 Config

Parameter

Mandatory

Type

Description

script

No

String

Definition: Custom script (Base64 encoding) or absolute path of a script.

Constraints: N/A

Range: N/A

Default Value: N/A

type

No

String

Definition: Script type.

Constraints: N/A

Range:

  • COMMAND: The script content (Base64-encoded) must be specified.

  • SCRIPT (default): The script path must be specified.

Default Value: N/A

Table 8 LeaseReq

Parameter

Mandatory

Type

Description

duration

No

Long

Definition: The instance stops as scheduled. Its runtime is measured in milliseconds starting now.

Constraints: N/A

Range: 3600000 to 259200000

Default Value: 3600000

type

No

String

Definition: Auto stop type.

Constraints: N/A

Range:

  • TIMING: auto stop

  • IDLE: stop when idle

Default Value: TIMING

Response Parameters

Status code: 200

Table 9 Response body parameters

Parameter

Type

Description

action_progress

Array of JobProgress objects

Definition: Initialization progress of the instance.

description

String

Definition: Instance description.

Range: N/A

endpoints

Array of EndpointsRes objects

Definition: Local IDE (such as PyCharm and VS Code) or SSH client for remotely accessing a notebook instance through SSH.

fail_reason

String

Definition: Instance failure cause.

Range: N/A

flavor

String

Definition: Instance flavor.

Range: N/A

id

String

Definition: Instance ID.

Range: N/A

image

Image object

Definition: Instance image information.

lease

Lease object

Definition: Countdown to auto stop of an instance.

name

String

Definition: Instance name.

Range: N/A

pool

Pool object

Definition: Basic information about the dedicated pool, which is returned by the instance created in the dedicated pool.

status

String

Definition: Instance status.

Range:

  • INIT: The instance is being initialized.

  • CREATING: The instance is being created.

  • STARTING: The instance is being started.

  • STOPPING: The instance is being stopped.

  • DELETING: The instance is being deleted.

  • RUNNING: The instance is running.

  • STOPPED: The instance has been stopped.

  • SNAPSHOTTING: The image of the instance is being saved.

  • CREATE_FAILED: Creating the instance failed.

  • START_FAILED: Starting the instance failed.

  • DELETE_FAILED: Deleting the instance failed.

  • ERROR: An error occurred.

  • DELETED: The instance has been deleted.

  • FROZEN: The instance is frozen.

token

String

Description: Token used for notebook authentication.

Range: N/A

url

String

Definition: URL for accessing the instance.

Range: N/A

volume

VolumeRes object

Definition: Instance storage information.

workspace_id

String

Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value.

Range: N/A

feature

String

Definition: Instance type.

Range:

  • DEFAULT: free CodeLab instance. Each user can create only one.

  • NOTEBOOK: billed instance.

billing_items

Array of strings

Definition: Billing resource type. Range:

  • STORAGE: Storage resource billing

  • COMPUTE: Computing resources billing

  • ALL: All billing types

user

user object

Description: Account information.

Table 10 JobProgress

Parameter

Type

Description

notebook_id

String

Definition: Instance ID.

Range: N/A

status

String

Definition: Job status in a specified step.

Range:

  • WAITING: The job is awaiting.

  • PROCESSING: The job is being processed.

  • FAILED: The job failed.

  • COMPLETED: The job is complete.

step

Integer

Definition: Job step.

Range:

  • 1: Prepare storage.

  • 2: Prepare compute resources.

  • 3: Configure the network.

  • 4: Initialize the instance.

step_description

String

Definition: Job description in a specified step.

Range: N/A

Table 11 EndpointsRes

Parameter

Type

Description

allowed_access_ips

Array of strings

Definition: Whitelisted public IP addresses that are allowed to access notebook instances through SSH. By default, all public IP addresses can access the notebook instances. If IP addresses are specified, only the clients with the specified IP addresses can access the notebook instances.

dev_service

String

Definition: Method for accessing the notebook instance.

Range:

  • NOTEBOOK: You can access notebook instances using HTTPS.

  • SSH: You can remotely access notebook instances through SSH.

ssh_keys

Array of strings

Definition: List of SSH key pairs. You can set multiple key pairs to access an SSH instance at the same time.

service

String

Definition: Method for accessing the notebook instance.

Range:

  • NOTEBOOK: You can access notebook instances using HTTPS.

  • SSH: You can remotely access notebook instances through SSH.

uri

String

Definition: Private IP address of the instance.

Range: N/A

Table 12 Image

Parameter

Type

Description

arch

String

Definition: Processor architecture supported by the image.

Range:

  • X86_64: x86 architecture

  • AARCH64: Arm architecture

create_at

Long

Definition: UTC time when the image is created, accurate to millisecond.

Range: N/A

description

String

Definition: Image description.

Range: Up to 512 characters

dev_services

Array of strings

Definition: Services supported by the image.

Range:

  • NOTEBOOK: You can access a notebook instance using HTTPS.

  • SSH: You can remotely access a notebook instance from a local IDE through SSH.

id

String

Definition: ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format. For details, see Querying Supported Images.

Range: N/A

name

String

Definition: Image name.

Range: The name can contain a maximum of 512 characters. Lowercase letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.

namespace

String

Definition: Organization to which the image belongs. You can create and view an organization on the Organization Management page of the SWR console.

Range: N/A

origin

String

Definition: Image source.

Range:

  • CUSTOMIZE: custom image

  • IMAGE_SAVE: image saved by a notebook instance

resource_categories

Array of strings

Definition: Flavors supported by the image. Range:

  • CPU

  • GPU

  • ASCEND

service_type

String

Definition: Supported image types.

Range:

  • COMMON: common image

  • INFERENCE: image used for inference

  • TRAIN: image used for training

  • DEV: image used for development and debugging

  • UNKNOWN: image whose supported services are not specified

size

Long

Definition: Image size, in KB.

Range: N/A

status

String

Definition: Image status.

Range:

  • INIT: The image is being initialized.

  • CREATING: The image is being saved. In this case, the notebook instance is unavailable.

  • CREATE_FAILED: Saving the image failed.

  • ERROR: An error occurs.

  • DELETED: The image has been deleted.

  • ACTIVE: The image has been saved, which you can view on the SWR console and use to create notebook instances.

status_message

String

Definition: Build information during image saving.

Range: N/A

support_res_categories

Array of strings

Definition: Flavors supported by the image. Range:

  • CPU

  • GPU

  • ASCEND

swr_path

String

Definition: SWR image path.

Range: N/A

tag

String

Definition: Image tag.

Range: N/A

type

String

Definition: Image type.

Range:

  • BUILD_IN: built-in system image

  • DEDICATED: image you have saved

update_at

Long

Definition: Time (UTC) when the image was last updated, accurate to millisecond.

Range: N/A

visibility

String

Definition: Image visibility.

Range:

  • PRIVATE: private image

  • PUBLIC: All users can perform read-only operations based on image_id.

workspace_id

String

Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value.

Range: N/A

flavor_type

String

Definition: Resource type of the image.

Range:

  • ASCEND_SNT9

  • ASCEND_SNT9B

  • ASCEND_SNT3

Table 13 Lease

Parameter

Type

Description

create_at

Long

Definition: UTC time when the instance is created, accurate to millisecond.

Range: N/A

duration

Long

Definition: Instance runtime, which is calculated based on the instance creation time. If the instance creation time plus the runtime is greater than the current time, the system automatically stops the instance.

Range: N/A

enable

Boolean

Definition: Specifies whether to enable auto stop.

Range: Boolean

  • true: Auto stop is enabled.

  • false: Auto stop is disabled.

type

String

Definition: Auto stop type.

Range:

  • TIMING: auto stop

  • IDLE: stop when idle

update_at

Long

Definition: Time (UTC) when the instance is last updated (excluding liveness check), accurate to millisecond.

Range: N/A

Table 14 Pool

Parameter

Type

Description

id

String

Definition: Dedicated resource pool ID.

Range: N/A

name

String

Definition: Dedicated resource pool name.

Range: N/A

Table 15 VolumeRes

Parameter

Type

Description

capacity

Integer

Definition: Storage capacity.

Range: The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4,096 GB.

category

String

Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron.

Range:

  • SFS

  • EVS

  • OBS

  • OBSFS: parallel file system

  • EFS: SFS Turbo

mount_path

String

Definition: Directory of the notebook instance to which the storage is mounted. Currently, the directory is /home/ma-user/work/.

Range: N/A

ownership

String

Definition: Resource owner.

Range:

  • MANAGED: Resources are managed by the service.

  • DEDICATED: Resources are managed by the user account. This mode is supported only when the instance category is EFS.

status

String

Definition: EVS disk capacity expansion status, which is RESIZING during capacity expansion and does not affect the instance.

Range: N/A

Table 16 user

Parameter

Type

Description

domain

domain object

Description: Domain information of the account.

id

String

Definition: IAM user ID. For details, see Obtaining a Username and ID.

Range: N/A

name

String

Definition: IAM username.

Range: N/A

Table 17 domain

Parameter

Type

Description

id

String

Definition: Account ID.

Range: N/A

name

String

Definition: Account name.

Range: N/A

Status code: 201

Created

Example Requests

The following is an example of how to create a notebook instance whose flavor is modelarts.vm.cpu.2u, storage type is evs, ownership is MANAGED, and storage capacity is 50 GB.

{
  "name" : "notebooks_test",
  "feature" : "NOTEBOOK",
  "workspace_id" : "0",
  "description" : "api-test",
  "flavor" : "modelarts.vm.cpu.2u",
  "image_id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
  "volume" : {
    "category" : "evs",
    "ownership" : "managed",
    "capacity" : 50
  }
}

Example Responses

Status code: 200

OK

{
  "description" : "api-test",
  "feature" : "NOTEBOOK",
  "flavor" : "modelarts.vm.cpu.2u",
  "id" : "f9937afa-4451-42db-a76b-72d624749f66",
  "image" : {
    "description" : "description",
    "id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
    "name" : "notebook2.0-mul-kernel-cpu-cp36",
    "swr_path" : "swr.xxxxx.com/atelier/notebook2.0-mul-kernel-cpu-cp36:3.3.2-release_v1",
    "tag" : "3.3.2-release_v1",
    "type" : "BUILD_IN"
  },
  "lease" : {
    "create_at" : 1638841744515,
    "duration" : 3600000,
    "enable" : true,
    "type" : "TIMING",
    "update_at" : 1638841744515
  },
  "name" : "notebooks_test",
  "status" : "CREATING",
  "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022",
  "workspace_id" : "0"
}

Status Codes

Status Code

Description

200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not found

Error Codes

See Error Codes.