Create

Create a Custom Image

post/v2/images

To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

Body ParametersExpand Collapse

description: optional string

An optional free-form text field to describe an image.

distribution: optional "Arch Linux" or "CentOS" or "CoreOS" or 10 more

The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place.

Accepts one of the following:

"Arch Linux"

"CentOS"

"CoreOS"

"Debian"

"Fedora"

"Fedora Atomic"

"FreeBSD"

"Gentoo"

"openSUSE"

"RancherOS"

"Rocky Linux"

"Ubuntu"

"Unknown"

name: optional string

The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.

region: optional "ams1" or "ams2" or "ams3" or 12 more

The slug identifier for the region where the resource will initially be available.

Accepts one of the following:

"ams1"

"ams2"

"ams3"

"blr1"

"fra1"

"lon1"

"nyc1"

"nyc2"

"nyc3"

"sfo1"

"sfo2"

"sfo3"

"sgp1"

"tor1"

"syd1"

tags: optional array of string

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

url: optional string

A URL from which the custom Linux virtual machine image may be retrieved. The image it points to must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.

ReturnsExpand Collapse

image: optional Image { id, created_at, description, 11 more }

id: optional number

A unique number that can be used to identify and reference a specific image.

created_at: optional string

A time value given in ISO8601 combined date and time format that represents when the image was created.

formatdate-time

description: optional string

An optional free-form text field to describe an image.

distribution: optional "Arch Linux" or "CentOS" or "CoreOS" or 10 more

Accepts one of the following:

"Arch Linux"

"CentOS"

"CoreOS"

"Debian"

"Fedora"

"Fedora Atomic"

"FreeBSD"

"Gentoo"

"openSUSE"

"RancherOS"

"Rocky Linux"

"Ubuntu"

"Unknown"

error_message: optional string

A string containing information about errors that may occur when importing a custom image.

min_disk_size: optional number

The minimum disk size in GB required for a Droplet to use this image.

minimum0

name: optional string

The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.

public: optional boolean

This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account.

regions: optional array of "ams1" or "ams2" or "ams3" or 12 more

This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.

Accepts one of the following:

"ams1"

"ams2"

"ams3"

"blr1"

"fra1"

"lon1"

"nyc1"

"nyc2"

"nyc3"

"sfo1"

"sfo2"

"sfo3"

"sgp1"

"tor1"

"syd1"

size_gigabytes: optional number

The size of the image in gigabytes.

formatfloat

slug: optional string

A uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id.

status: optional "NEW" or "available" or "pending" or 2 more

A status string indicating the state of a custom image. This may be NEW, available, pending, deleted, or retired.

Accepts one of the following:

"NEW"

"available"

"pending"

"deleted"

"retired"

tags: optional array of string

A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags.

Requires tag:create scope.

type: optional "base" or "snapshot" or "backup" or 2 more

Describes the kind of image. It may be one of base, snapshot, backup, custom, or admin. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes).

Accepts one of the following:

"base"

"snapshot"

"backup"

"custom"

"admin"

Create a Custom Image

curl https://api.digitalocean.com/v2/images \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" \
    -d '{
          "description": " ",
          "distribution": "Ubuntu",
          "name": "Nifty New Snapshot",
          "region": "nyc3",
          "tags": [
            "base-image",
            "prod"
          ],
          "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img"
        }'

{
  "image": {
    "id": 7555620,
    "created_at": "2020-05-04T22:23:02Z",
    "description": " ",
    "distribution": "Ubuntu",
    "error_message": " ",
    "min_disk_size": 20,
    "name": "Nifty New Snapshot",
    "public": true,
    "regions": [
      "nyc1",
      "nyc2"
    ],
    "size_gigabytes": 2.34,
    "slug": "nifty1",
    "status": "NEW",
    "tags": [
      "base-image",
      "prod"
    ],
    "type": "snapshot"
  }
}

Returns Examples

{
  "image": {
    "id": 7555620,
    "created_at": "2020-05-04T22:23:02Z",
    "description": " ",
    "distribution": "Ubuntu",
    "error_message": " ",
    "min_disk_size": 20,
    "name": "Nifty New Snapshot",
    "public": true,
    "regions": [
      "nyc1",
      "nyc2"
    ],
    "size_gigabytes": 2.34,
    "slug": "nifty1",
    "status": "NEW",
    "tags": [
      "base-image",
      "prod"
    ],
    "type": "snapshot"
  }
}