---
title: "Create a Custom Image"
method: POST
path: "/v2/images"
tags: ["DigitalOcean-public.v2-new_Images"]
---

# 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.

## Request body

- ImageNewCustom
  - `name` string, required — 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.
  - `distribution` 'Arch Linux' | 'CentOS' | 'CoreOS' | 'Debian' | 'Fedora' | 'Fedora Atomic' | 'FreeBSD' | 'Gentoo' | 'openSUSE' | 'RancherOS' | 'Rocky Linux' | 'Ubuntu' | 'Unknown' — 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.
  - `description` string — An optional free-form text field to describe an image.
  - `url` string, required — 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.
  - `region` 'ams1' | 'ams2' | 'ams3' | 'blr1' | 'fra1' | 'lon1' | 'nyc1' | 'nyc2' | 'nyc3' | 'sfo1' | 'sfo2' | 'sfo3' | 'sgp1' | 'tor1' | 'syd1', required — The slug identifier for the region where the resource will initially be available.
  - `tags` string[], nullable — A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. <br><br>Requires `tag:create` scope.

## Response `202`

The response will be a JSON object with a key set to `image`.  The value of this will be an image object containing a subset of the standard  image attributes as listed below, including the image's `id` and `status`.  After initial creation, the `status` will be `NEW`. Using the image's id, you  may query the image's status by sending a `GET` request to the  `/v2/images/$IMAGE_ID` endpoint.  When the `status` changes to `available`, the image will be ready for use.

- object
  - `image` Image
    - `id` integer — A unique number that can be used to identify and reference a specific image.
    - `name` 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.
    - `type` 'base' | 'snapshot' | 'backup' | 'custom' | 'admin' — 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).
    - `distribution` 'Arch Linux' | 'CentOS' | 'CoreOS' | 'Debian' | 'Fedora' | 'Fedora Atomic' | 'FreeBSD' | 'Gentoo' | 'openSUSE' | 'RancherOS' | 'Rocky Linux' | 'Ubuntu' | 'Unknown' — 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.
    - `slug` string, nullable — 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.
    - `public` 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` RegionSlug[] — This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.
    - `created_at` string, date-time — A time value given in ISO8601 combined date and time format that represents when the image was created.
    - `min_disk_size` integer, nullable — The minimum disk size in GB required for a Droplet to use this image.
    - `size_gigabytes` number, float, nullable — The size of the image in gigabytes.
    - `description` string — An optional free-form text field to describe an image.
    - `tags` string[], nullable — A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. <br><br>Requires `tag:create` scope.
    - `status` 'NEW' | 'available' | 'pending' | 'deleted' | 'retired' — A status string indicating the state of a custom image. This may be `NEW`, `available`, `pending`, `deleted`, or `retired`.
    - `error_message` string — A string containing information about errors that may occur when importing a custom image.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/revisions/cb3bf9b21459/schema)