Compute > Image > API v2 Guide

To use the API, API endpoint and token are required. Refer to API usage preparations to prepare the information required to use the API.

Image API uses the image type endpoint. Refer to the serviceCatalog in the token issuance response for the valid endpoint.

Type Region Endpoint
image Korea (Pangyo) Region
Korea (Pyeongchon) Region
Japan Region
https://kr1-api-image.infrastructure.cloud.toast.com
https://kr2-api-image.infrastructure.cloud.toast.com
https://jp1-api-image.infrastructure.cloud.toast.com

In API response, you may find fields that are not specified in the guide. These fields are only for the internal use by NHN Cloud and are subject to change without prior notice, so we advise you not to use them.

Image

List Images

GET /v2/images
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
tokenId Header String O Token ID
limit Query Integer - Image count to return (default is 20)
marker Query UUID - ID of the first image on the list to query
Query as much as the limit after image specified as the marker according to the sorting order
name Query String - Name of image to query
visibility Query Enum - Visibility attribute of the image to query
Select only one of public, private, and shared
If left blank, list of all types of images are returned.
owner Query String - ID of the tenant to which the image to query belongs
status Query Enum - Image status to query
queued: Converting image
saving: Uploading image
active: Normal
killed: Deleting image from system
deleted: Image deleted
pending_delete: Delete Image is pending
size_min Query Integer - Minimum size of image to query (bytes)
size_max Query Integer - Maximum size of image to query (bytes)
nhncloud_product Query Enum - Infrastructure service type of image to query
compute: Instance service image
gpu: GPU Instance service image
sort_key Query String - Attribute to use when sorting the image list
All attributes of image can be specified, default is created_at
sort_dir Query Enum - Sorting direction of the image list
Select only one of asc (ascending order) or desc (descending order)

Response

Name Type Format Description
images Body Array Image list object
images.status Body String Image status
One of queued, saving, active, killed, deleted, and pending_delete
images.name Body String Image name
images.tag Body String Image tag
If you delete the _AVAILABLE_ tag, it will not be queried in the console, so be careful not to delete the tag.
images.container_format Body String Image container format
images.created_at Body Datetime Creation time
images.disk_format Body String Image disk format
images.updated_at Body Datetime Modification time
images.min_disk Body Integer Minimum required disk size of image (GB)
Available only for volumes that are larger than min_disk
images.protected Body Boolean Protect image or not
Cannot be modified or deleted when protected=true
images.id Body UUID Image ID
images.min_ram Body Integer Minimum required memory size of image (MB)
Available only for instances that are larger than min_disk
images.checksum Body String Hash for image content
Used internally for image validation
images.owner Body String ID of the tenant to which the image belongs
images.visibility Body Enum Image visibility
One of public, private, and shared
images.virtual_size Body Integer Virtual size of the image
images.size Body Integer Real size of the image (bytes)
images.properties Body Object Image properties object
Describes user-specified properties for each image in the key-value pair format
images.self Body URI Image path
images.file Body String File path of image
images.schema Body URI Schema path of image
schema Body URI Schema path of image list
first Body URI Path of the first page of image list
next Body URI Path of the next page of image list
Example

{
  "images": [
    {
      "container_format": "bare",
      "min_ram": 0,
      "updated_at": "2018-12-11T01:01:35Z",
      "login_username": "centos",
      "file": "/v2/images/1c868787-6207-4ff2-a1e7-ae1331d6829b/file",
      "owner": "c289b99209ca4e189095cdecebbd092d",
      "id": "1c868787-6207-4ff2-a1e7-ae1331d6829b",
      "size": 1778843648,
      "os_distro": "CentOS",
      "self": "/v2/images/1c868787-6207-4ff2-a1e7-ae1331d6829b",
      "disk_format": "qcow2",
      "os_version": "6.10",
      "schema": "/v2/schemas/image",
      "status": "active",
      "description": "CentOS 6.10 (2018.10.23)",
      "tags": [],
      "visibility": "public",
      "os_architecture": "amd64",
      "min_disk": 20,
      "virtual_size": null,
      "name": "CentOS 6.10 (2018.10.23)",
      "hypervisor_type": "qemu",
      "created_at": "2018-10-23T02:17:43Z",
      "protected": true,
      "checksum": "f803c5c15bcf9a75935980a900a04584",
      "os_type": "linux"
    }
  ],
  "schema": "/v2/schemas/images",
  "first": "/v2/images",
  "next": "/v2/images?marker=057f9a69-4e4c-4025-8a69-fa248cd9db94"
}


Get Image

GET /v2/images/{imageId}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O Image ID to query
tokenId Header String O Token ID

Response

Name Type Format Description
image.status Body String Image status
image.name Body String Image name
image.tag Body String Image tags
If you delete the _AVAILABLE_ tag, it will not be queried in the console, so be careful not to delete the tag.
image.container_format Body String Image container format
image.created_at Body Datetime Creation time
image.disk_format Body String Image disk format
image.updated_at Body Datetime Modification time
image.min_disk Body Integer Minimum required disk size of image (GB)
Available only for instances that are larger than min_disk
image.protected Body boolean Protect image or not
Cannot be modified or deleted when protected=true
image.id Body UUID Image ID
image.min_ram Body Integer Minimum required memory size of image (MB)
Available only for instances that are larger than min_disk
image.checksum Body String Hash for image content
Used internally for image validation
image.owner Body String ID of the tenant to which the image belongs
image.visibility Body Enum Image visibility
One of public, private, and shared
image.virtual_size Body Integer Virtual size of the image
image.size Body Integer Real size of the image (bytes)
image.properties Body Object Image properties object
Describes user-specified properties for each image in the key-value pair format
image.self Body URI Image path
image.file Body String File path of image
image.schema Body URI Schema path of image
Example

{
  "container_format": "bare",
  "min_ram": 0,
  "updated_at": "2018-12-11T01:01:35Z",
  "login_username": "centos",
  "file": "/v2/images/1c868787-6207-4ff2-a1e7-ae1331d6829b/file",
  "owner": "c289b99209ca4e189095cdecebbd092d",
  "id": "1c868787-6207-4ff2-a1e7-ae1331d6829b",
  "size": 1778843648,
  "os_distro": "CentOS",
  "self": "/v2/images/1c868787-6207-4ff2-a1e7-ae1331d6829b",
  "disk_format": "qcow2",
  "os_version": "6.10",
  "schema": "/v2/schemas/image",
  "status": "active",
  "description": "CentOS 6.10 (2018.10.23)",
  "tags": [],
  "visibility": "public",
  "os_architecture": "amd64",
  "min_disk": 20,
  "virtual_size": null,
  "name": "CentOS 6.10 (2018.10.23)",
  "hypervisor_type": "qemu",
  "created_at": "2018-10-23T02:17:43Z",
  "protected": true,
  "checksum": "f803c5c15bcf9a75935980a900a04584",
  "os_type": "linux"
}


Delete Image

Images with public visibility cannot be deleted.

DELETE /v2/images/{imageId}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL String O Image ID to delete
tokenId Header String O Token ID

Response

This API does not return response body.


Image Tag

Add Tag

Adds a tag to the specified image.

PUT /v2/images/{imageId}/tags/{tag}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O ID of the image to add a tag
tag URL String O Name of the tag to add (no more than 255 letters in English)
(Caution) Tags starting with _ are not allowed
tokenId Header String O Token ID

Response

This API does not return response body.


Remove Tag

Removes a tag from the specified image.

DELETE /v2/images/{imageId}/tags/{tag}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O ID of the image to remove the tag
tag URL String O Name of the tag to remove
tokenId Header String O Token ID

Response

This API does not return a response body.


Image Sharing

Image sharing allows you to share images belonging to your tenant with other tenants. You can share your images as follows:

  1. Change the image visibility to shared.
  2. Register the tenant to share the image with as a member of the image.

The shared image becomes immediately available to the target tenant, but is not displayed in the image list query. If you change the member status to active in Shared Tenant, the shared image can be queried.

Change Visibility

PATCH /v2/images/{imageId}
X-Auth-Token: {tokenId}
Content-Type: application/openstack-images-v2.1-json-patch

Request

Name Type Format Required Description
imageId URL UUID O ID of the image to share
tokenId Header String O Token ID
op Body String O Specify as replace
path Body String O Specify as /visibility
value Body String O Visibility value to change, private or shared
Example

[
    {
        "op" : "replace",
        "path" : "/visibility",
        "value" : "shared"
    }
]

Response

Returns the same response as Get Image.


Add Member

Registers the tenant to share the image with as a member of the specified image.

POST /v2/images/{imageId}/members
X-Auth-Token: {tokenId}

The maximum number of members in an image is limited to 127.

Request

Name Type Format Required Description
imageId URL UUID O ID of the image to share
tokenId Header String O Token ID
member Body String O Tenant ID to share the image with
Example

{
    "member": "8989447062e04a818baf9e073fd04fa7"
}

Response

Name Type Format Description
created_at Body Datetime Member creation time
In YYYY-MM-DDThh:mm:ssZ format
image_id Body UUID ID of the shared image
member_id Body String ID of the target tenant for image sharing
schema Body URI Schema path of the image member
status Body Enum Status of the image member
Either pending or accepted
Example

{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "pending",
    "updated_at": "2013-09-20T19:25:31Z"
}


List Members

Retrieves the list of tenants that the specified image has been shared with. The request must be made with the token of the tenant to which the image belongs or the target tenant of the image sharing.

GET /v2/images/{imageId}/members
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O Image ID
tokenId Header String O Token ID

Response

Name Type Format Description
members Body Object List of member objects
members.created_at Body Datetime Member creation time, in YYYY-MM-DDThh:mm:ssZ format
members.image_id Body UUID ID of the shared image
members.member_id Body String ID of the target tenant for image sharing
members.schema Body URI Schema path of the image member
members.status Body Enum Status of the image member
Either pending or accepted
schema Body URI Schema path for the list of image members
Example

{
    "members": [
        {
            "created_at": "2013-10-07T17:58:03Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "123456789",
            "schema": "/v2/schemas/member",
            "status": "pending",
            "updated_at": "2013-10-07T17:58:03Z"
        },
        {
            "created_at": "2013-10-07T17:58:55Z",
            "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
            "member_id": "987654321",
            "schema": "/v2/schemas/member",
            "status": "accepted",
            "updated_at": "2013-10-08T12:08:55Z"
        }
    ],
    "schema": "/v2/schemas/members"
}


Get Member Details

Returns details of a particular member of specified image. The request must be made with the token of the tenant to which the image belongs or the target tenant of the image sharing.

GET /v2/images/{imageId}/members/{memberId}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O Image ID
memberId URL String O Member ID
tokenId Header String O Token ID

Response

Name Type Format Description
created_at Body Datetime Member creation time in YYYY-MM-DDThh:mm:ssZ format
image_id Body UUID ID of the shared image
member_id Body String ID of the target tenant for image sharing
schema Body URI Schema path of the image member
status Body Enum Status of the image member, either pending or accepted
Example

{
    "status": "pending",
    "created_at": "2013-11-26T07:21:21Z",
    "updated_at": "2013-11-26T07:21:21Z",
    "image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member"
}


Change Member Status

The shared image is approved by the sharing target tenant. If the image sharing is approved, the image can be queried in the image list query. The request must be made with the sharing target tenant's token.

PUT /v2/images/{imageId}/members/{memberId}
X-Auth-Token: {tokenId}

Request

Name Type Format Required Description
imageId URL UUID O Image ID
memberId URL String O Member ID
tokenId Header String O Token ID
status Body Enum O One of accepted, pending, or rejected
Example

{
    "status": "accepted"
}

Response

Name Type Format Description
created_at Body Datetime Member creation time
In YYYY-MM-DDThh:mm:ssZ format
image_id Body UUID ID of shared image
member_id Body String ID of the target tenant for image sharing
schema Body URI Schema path of the image member
status Body Enum Status of the image member
One of accepted,pending, or rejected
updated_at Body Datetime Member status modification time
In YYYY-MM-DDThh:mm:ssZ format
Example

{
    "created_at": "2013-09-20T19:22:19Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "8989447062e04a818baf9e073fd04fa7",
    "schema": "/v2/schemas/member",
    "status": "accepted",
    "updated_at": "2013-09-20T20:15:31Z"
}


Delete Member

Deletes a member of the specified image. This is used to cancel sharing. The request must be made with the token of the tenant to which the specified image belongs.

DELETE /v2/images/{imageId}/members/{memberId}
X-Auth-Token: {tokenId}

Request

This API does not require a request body.

Name Type Format Required Description
imageId URL UUID O Image ID
memberId URL String O Member ID
tokenId Header String O Token ID

Response

This API does not return a response body.

TOP