Skip to main content

Creating image records

POST /v2/images

Create an image record. You must provide a name and specify container_format and disk_format. After creating the record, upload image data to the image according to the "Uploading image data" flow.

Request

Parameters

NameInTypeDescription
container_format (Optional)bodyenumFormat of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. Example formats are: ami, ari, aki, bare, ovf, ova, or docker. The value might be null (JSON null data type).
disk_format (Optional)bodyenumThe format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type).
id (Optional)bodystringA unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb. If you omit this value, the API generates a UUID for the image. If you specify a value that has already been assigned, the request fails with a 409 response code.
min_disk (Optional)bodyintegerAmount of disk space in GB that is required to boot the image.
min_ram (Optional)bodyintegerAmount of RAM in MB that is required to boot the image.
name (Optional)bodystringThe name of the image.
protected (Optional)bodybooleanImage protection for deletion. Valid value is true or false. Default is false.
tags (Optional)bodyarrayList of tags for this image. Each tag is a string of at most 255 chars. The maximum number of tags allowed on an image is set by the operator.
visibility (Optional)bodystringVisibility for this image. Valid value is one of: public, private, shared, or community. At most sites, only an administrator can make an image public. Some sites may restrict what users can make an image community. Some sites may restrict what users can perform member operations on a shared image. Since the Image API v2.5, the default value is shared.

Example

curl -ks -X POST \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: gAAAAA<...>' \
-d '{
"container_format": "bare",
"disk_format": "qcow2",
"name": "alpine"
}' \
https://api.vietnix.cloud:9292/v2/images

Response

Parameters

NameInTypeDescription
LocationheaderstringThe URL to access the image file from the external store.
OpenStack-image-import-methods (Optional)headerstringA comma separated list of import method identifiers. Included only if image import is enabled in your cloud. New in version 2.6
OpenStack-image-store-ids (Optional)headerstringA comma separated list of available store identifiers. If this header is missing the cloud does not support multiple backend stores.
checksumbodystringHash that is used over the image data. The Image service uses this value for verification. The value might be null (JSON null data type).
container_formatbodyenumFormat of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. Example formats are: ami, ari, aki, bare, ovf, ova, or docker. The value might be null (JSON null data type).
created_atbodystringThe date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
disk_formatbodyenumThe format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type).
filebodystringThe URL for the virtual machine image file.
idbodystringA unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb. If you omit this value, the API generates a UUID for the image.
min_diskbodyintegerAmount of disk space in GB that is required to boot the image. The value might be null (JSON null data type).
min_rambodyintegerAmount of RAM in MB that is required to boot the image. The value might be null (JSON null data type).
namebodystringThe name of the image. Value might be null (JSON null data type).
os_hash_algobodystringThe algorithm used to compute a secure hash of the image data for this image. The result of the computation is displayed as the value of the os_hash_value property. The value might be null (JSON null data type). The algorithm used is chosen by the cloud operator; it may not be configured by end users. New in version 2.7
os_hash_valuebodystringThe hexdigest of the secure hash of the image data computed using the algorithm whose name is the value of the os_hash_algo property. The value might be null (JSON null data type) if data has not yet been associated with this image, or if the image was created using a version of the Image Service API prior to version 2.7. New in version 2.7
os_hiddenbodybooleanThis field controls whether an image is displayed in the default image-list response. A "hidden" image is out of date somehow (for example, it may not have the latest updates applied) and hence should not be a user's first choice, but it's not deleted because it may be needed for server rebuilds. By hiding it from the default image list, it's easier for end users to find and use a more up-to-date version of this image. New in version 2.7
ownerbodystringAn identifier for the owner of the image, usually the project (also called the "tenant") ID. The value might be null (JSON null data type).
protectedbodybooleanA boolean value that must be false or the image cannot be deleted.
schemabodystringThe URL for the schema describing a virtual machine image.
selfbodystringThe URL for the virtual machine image.
sizebodyintegerThe size of the image data, in bytes. The value might be null (JSON null data type).
statusbodystringThe image status.
tagsbodyarrayList of tags for this image, possibly an empty list.
updated_atbodystringThe date and time when the resource was updated. If the resource has not been updated, this field will be null. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
virtual_sizebodyintegerThe virtual size of the image. The value might be null (JSON null data type).
visibilitybodystringImage visibility, that is, the access permission for the image.
direct_url (Optional)bodystringThe URL to access the image file kept in external store. It is present only if the show_image_direct_url option is true in the Image service's configuration file. As it presents a security risk, this option is disabled by default.
locations (Optional)bodyarrayA list of objects, each of which describes an image location. Each object contains a url key, whose value is a URL specifying a location, and a metadata key, whose value is a dict of key:value pairs containing information appropriate to the use of whatever external store is indicated by the URL. This list appears only if the show_multiple_locations option is set to true in the Image service's configuration file. As it presents a security risk, this option is disabled by default.

Example response

{
"name": "alpine",
"disk_format": "qcow2",
"container_format": "bare",
"visibility": "shared",
"size": null,
"virtual_size": null,
"status": "queued",
"checksum": null,
"protected": false,
"min_ram": 0,
"min_disk": 0,
"owner": "f33507157a634f1cac71e06a70fb558e",
"os_hidden": false,
"os_hash_algo": null,
"os_hash_value": null,
"id": "9775d86a-8bf8-4200-a4b5-d892e931e8f6",
"created_at": "2025-10-22T08:40:44Z",
"updated_at": "2025-10-22T08:40:44Z",
"tags": [],
"self": "/v2/images/9775d86a-8bf8-4200-a4b5-d892e931e8f6",
"file": "/v2/images/9775d86a-8bf8-4200-a4b5-d892e931e8f6/file",
"schema": "/v2/schemas/image"
}

Status codes

Success

CodeReason
201 - CreatedResource was created and is ready to use.

Error

CodeReason
400 - Bad RequestSome content in the request was invalid.
401 - UnauthorizedUser must authenticate before making a request.
403 - ForbiddenPolicy does not allow current user to do this operation.
409 - ConflictThis operation conflicted with another operation on this resource.
413 - Request Entity Too LargeThe request is larger than the server is willing or able to process.
415 - Unsupported Media TypeThe request entity has a media type which the server or resource does not support.
  • 401 Unauthorized — Authentication required.
  • 403 Forbidden — Policy prevents the operation.
  • 409 Conflict — Conflicting operation or duplicate id.
  • 413 Request Entity Too Large — Upload is larger than server accepts.
  • 415 Unsupported Media Type — Provided media type is not supported.