Help Center/ Workspace/ API Reference/ Workspace Application Streaming APIs/ Image Management/ Creating an Image Instance
Updated on 2026-05-21 GMT+08:00
View PDF
Share

Creating an Image Instance

Function

Creates an image instance.

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:imageServer:create

    Write

    imageServer *

    -

    -
    • ims:images:list
    • vpc:ports:get
    • vpc:subnets:get

    -

    g:EnterpriseProjectId

URI

POST /v1/{project_id}/image-servers

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Unique ID of a project

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token.

It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Service-Transaction-Id

No

String

Service ID in the request header when the CBC API is called back.

X-Linked-Id

No

String

Associated ID delivered when the transaction component is invoked.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Image instance name. Requirements:

  1. Contains letters, digits, underscores (_), and hyphens (-). Spaces are not allowed.

  2. Contains 1 to 64 characters.

description

No

String

Image instance description.

root_volume

Yes

Volume object

System disk configuration of the image instance.

image_ref

Yes

ImageRef object

Image source information.

vpc_id

Yes

String

Unique ID of the VPC where the image instance is.

subnet_id

Yes

String

Unique ID of the subnet where the image instance network interface is.

product_id

Yes

String

Image instance product package ID.

flavor_id

No

String

Specification ID.

availability_zone

No

String

AZ of an image instance. If this parameter is left blank, an AZ is randomly selected.

attach_apps

No

Array of strings

List of unique IDs of software in the cloud application repository.

authorize_accounts

Yes

Array of ImageAccountInfo objects

Grants users the permission to use applications in an application group.

  • Restricted user type: USER

ou_name

No

String

Organization Name.

is_vdi

No

Boolean

Indicates whether the VDI single-session mode is used.

scheduler_hints

No

WdhParam object

Workspace DeH parameter.

extra_session_type

No

String

Paid session type:

GPU: GPU session

CPU: common CPU session

extra_session_size

No

Integer

Number of paid sessions.

route_policy

No

RoutePolicy object

Routing.

tags

No

Array of TmsTag objects

Tag information. A maximum of 20 keys are allowed and each of them must be unique.

enterprise_project_id

No

String

⚠: This attribute is reserved and no value is required. Currently, the image product belongs to the default enterprise project by default.

ID of the enterprise project to which the image belongs. The default value is the default enterprise project.

For details about how to obtain enterprise project IDs and enterprise project characteristics, see Enterprise Center Overview.
Table 4 Volume

Parameter

Mandatory

Type

Description

type

Yes

String

Disk type. For details about how to obtain available disk types, see parameter ListVolumeType. Options:

ESSD: Extreme SSD

SSD: Ultra-high I/O

GPSSD: General-purpose SSD

SAS: High I/O

SATA: Common I/O

size

Yes

Integer

Disk capacity (a multiple of 10, in GB). Options:

  • System disk: minLength: 10; maxLength: 1024

  • Data disk: minLength: 10; maxLength: 32768.

cluster_id

No

String

ID of the storage pool used by the ECS system disk.
Table 5 ImageRef

Parameter

Mandatory

Type

Description

id

Yes

String

Unique ID of the image source.

image_type

Yes

String

Image source type. Options:

gold: KooGallery image

public: public image

private: private image

shared: shared image

other: other images

spce_code

No

String

Specification code of the image source. This parameter is mandatory when the value of image type is set to gold.

product_id

No

String

Product ID of the image source. This parameter is mandatory when the value of image type is set to gold.
Table 6 ImageAccountInfo

Parameter

Mandatory

Type

Description

account

Yes

String

User (group).

account_type

Yes

String

User type.

USER: user

USER_GROUP: user group.

domain

No

String

Domain name.
Table 7 WdhParam

Parameter

Mandatory

Type

Description

dedicated_host_id

No

String

Workspace host ID.

tenancy

No

String

Type.
Table 8 RoutePolicy

Parameter

Mandatory

Type

Description

max_session

No

Integer

Maximum number of sessions on a single server.

cpu_threshold

No

Integer

CPU usage threshold, in percentage.

mem_threshold

No

Integer

Memory usage threshold (%).
Table 9 TmsTag

Parameter

Mandatory

Type

Description

key

Yes

String

Key. The value can contain a maximum of 128 Unicode characters.

  1. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @

  2. The value cannot start or end with a space.

value

No

String

Value. Each value can contain a maximum of 255 Unicode characters.

The value can contain UTF-8 letters, digits, spaces, or the following special characters: _ . : = + - @

Response Parameters

Status code: 200

Table 10 Response body parameters

Parameter

Type

Description

job_id

String

Job ID.

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.

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.

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.

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.

Status code: 405

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 409

Table 16 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 500

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Status code: 503

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error message.

Example Requests

POST /v1/a4da8115c9d8464ead3a38309130523f/image-servers

{
  "name" : "Image task 0508",
  "description" : "Test image creation.",
  "availability_zone" : "",
  "image_ref" : {
    "id" : "da02e5ca-c6ec-4685-8ecb-f116bb5bdd2c",
    "image_type" : "gold",
    "spce_code" : "90a6e84bb3e822fe54999b6be5bbae1e",
    "product_id" : "OFFI874943784560095232"
  },
  "vpc_id" : "59785ba5-e5d5-4836-b9de-19f22ac15175",
  "subnet_id" : "a5842cb4-5718-4b0a-8b27-3a3e9c74f977",
  "product_id" : "workspace.x86.performance.xlarge4",
  "attach_apps" : [ ],
  "authorize_accounts" : [ {
    "account" : "administrator",
    "account_type" : "USER",
    "domain" : "wksapp**.huawei.com"
  } ],
  "ou_name" : null,
  "root_volume" : {
    "type" : "SATA",
    "size" : 60
  },
  "is_vdi" : true
}

Example Responses

Status code: 200

Response to a successful request.

{
  "job_id" : "697612196825268224"
}

Status Codes

Status Code

Description

200

Response to a successful request.

400

The request cannot be understood by the server due to malformed syntax.

401

Authentication failed.

403

Permissions required.

404

No resources found.

405

The request method is not allowed.

409

Request conflict.

500

An internal service error occurred. For details, see the error code description.

503

Service unavailable.

Error Codes

See Error Codes.

Parent topic: Image Management