Registering a Custom Image

Function

This API is used to register a custom image with ModelArts image management.

This API applies to the following scenario: When you need to integrate a custom image (such as a specific algorithm environment, tool chain, or configuration) into ModelArts, you can use this API to register the image with image management for future use. Before using this API, ensure that you have the ModelArts image management permission and valid image path and the required image format are provided. After the registration is complete, the custom image is successfully added to the ModelArts image list. You can use this image subsequently. If the image path is invalid, the image format does not meet the requirements, or you do not have the relevant permission, the API will return an 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. Obtain its CLI example hcloud ModelArts RegisterImage.

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
modelarts:image:register	Write	image *	-	-	-
modelarts:image:register	Write	-	g:EnterpriseProjectId	-	-

URI

POST /v1/{project_id}/images

**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
arch	No	String	Definition: Processor architecture supported by the image. Constraints: N/A Range: X86_64: x86 architecture AARCH64: Arm architecture Default Value: x86_64
description	No	String	Definition: Image description. Constraints: N/A Range: Up to 512 characters Default Value: N/A
origin	No	String	Definition: Image source. This parameter is optional. Constraints: N/A Range: CUSTOMIZE: custom image IMAGE_SAVE: image saved by a notebook instance Default Value: CUSTOMIZE
resource_category	No	Array of strings	Definition: Flavor supported by the image. The default value is CPU or GPU. Range: CPU GPU ASCEND Constraints: N/A
service_type	No	String	Definition: Supported image types. Constraints: N/A 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 Default Value: UNKNOWN
services	No	Array of strings	Definition: Services supported by the image. The default value is NOTEBOOK or SSH. Range: NOTEBOOK: You can access a notebook instance using HTTPS. SSH: You can remotely access a notebook instance from a local IDE through SSH. Constraints: N/A
swr_path	Yes	String	Definition: SWR image path. Constraints: N/A Range: The value can contain 16 to 2,048 characters. The address format is [repository_address[:port]]/[namespace]/[image_name]:[tag]. Default Value: N/A
visibility	No	String	Definition: Image visibility. Constraints: N/A Range: PRIVATE: private image PUBLIC: All users can perform read-only operations based on image_id. Default Value: PRIVATE
workspace_id	No	String	Definition: Workspace ID. [For details about how to obtain the ID, see Querying the Workspace List.] (tag:hc,hk)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 must contain 0 or 32 characters. Only digits or lowercase letters are allowed. Default Value: 0
flavor_type	No	String	Definition: Resource type. Constraints: N/A Range: ASCEND_SNT9: 910 chip ASCEND_SNT9B: 910B chip ASCEND_SNT3: 310 chip Default Value: N/A

Response Parameters

Status code: 200

**Table 3** Response body parameters
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
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
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
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: 910 chip ASCEND_SNT9B: 910B chip ASCEND_SNT3: 310 chip

Status code: 201

Created

Example Requests

The following is an example of how to register a custom image whose resource type is CPU and architecture is X86_64.

{
  "description" : "",
  "resource_category" : [ "CPU" ],
  "arch" : "X86_64",
  "swr_path" : "swr.xxx.com/op_svc_modelarts_container2/pytorch_1_8:train-pytorch_1.8.0-cuda_10.2-py_3.7"
}

Example Responses

Status code: 200

{
  "arch" : "x86_64",
  "create_at" : 1671708630448,
  "description" : "",
  "id" : "708ca95d-c601-4dc7-86b9-670adfd5e818",
  "name" : "pytorch_1_8",
  "namespace" : "op_svc_modelarts_container2",
  "resource_categories" : [ "CPU" ],
  "service_type" : "UNKNOWN",
  "size" : 3376133259,
  "status" : "ACTIVE",
  "swr_path" : "swr.xxx.com/op_svc_modelarts_container2/pytorch_1_8:train-pytorch_1.8.0-cuda_10.2-py_3.7",
  "tag" : "train-pytorch_1.8.0-cuda_10.2-py_3.7",
  "type" : "DEDICATED",
  "update_at" : 1671708630448,
  "visibility" : "PRIVATE",
  "workspace_id" : "0"
}