# Images

## Create

`gpu_droplets.images.create(ImageCreateParams**kwargs)  -> ImageCreateResponse`

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

### Parameters

- **description:** `str`

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

- **distribution:** `Literal["Arch Linux", "CentOS", "CoreOS", 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.

  - `"Arch Linux"`

  - `"CentOS"`

  - `"CoreOS"`

  - `"Debian"`

  - `"Fedora"`

  - `"Fedora Atomic"`

  - `"FreeBSD"`

  - `"Gentoo"`

  - `"openSUSE"`

  - `"RancherOS"`

  - `"Rocky Linux"`

  - `"Ubuntu"`

  - `"Unknown"`

- **name:** `str`

  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:** `Literal["ams1", "ams2", "ams3", 12 more]`

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

  - `"ams1"`

  - `"ams2"`

  - `"ams3"`

  - `"blr1"`

  - `"fra1"`

  - `"lon1"`

  - `"nyc1"`

  - `"nyc2"`

  - `"nyc3"`

  - `"sfo1"`

  - `"sfo2"`

  - `"sfo3"`

  - `"sgp1"`

  - `"tor1"`

  - `"syd1"`

- **tags:** `Optional[List[str]]`

  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.

- **url:** `str`

  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.

### Returns

- `class ImageCreateResponse`

  - **image:** `Optional[Image]`

### Example

```python
from gradient import Gradient

client = Gradient()
image = client.gpu_droplets.images.create()
print(image.image)
```

## Retrieve

`gpu_droplets.images.retrieve(Union[int, str]image_id)  -> ImageRetrieveResponse`

**get** `/v2/images/{image_id}`

To retrieve information about an image, send a `GET` request to
`/v2/images/$IDENTIFIER`.

### Parameters

- **image\_id:** `Union[int, str]`

  - **ImageIDUnionMember0:** `int`

  - **ImageIDUnionMember1:** `str`

### Returns

- `class ImageRetrieveResponse`

  - **image:** `Image`

### Example

```python
from gradient import Gradient

client = Gradient()
image = client.gpu_droplets.images.retrieve(
    0,
)
print(image.image)
```

## Update

`gpu_droplets.images.update(intimage_id, ImageUpdateParams**kwargs)  -> ImageUpdateResponse`

**put** `/v2/images/{image_id}`

To update an image, send a `PUT` request to `/v2/images/$IMAGE_ID`.
Set the `name` attribute to the new value you would like to use.
For custom images, the `description` and `distribution` attributes may also be updated.

### Parameters

- **image\_id:** `int`

- **description:** `str`

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

- **distribution:** `Literal["Arch Linux", "CentOS", "CoreOS", 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.

  - `"Arch Linux"`

  - `"CentOS"`

  - `"CoreOS"`

  - `"Debian"`

  - `"Fedora"`

  - `"Fedora Atomic"`

  - `"FreeBSD"`

  - `"Gentoo"`

  - `"openSUSE"`

  - `"RancherOS"`

  - `"Rocky Linux"`

  - `"Ubuntu"`

  - `"Unknown"`

- **name:** `str`

  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.

### Returns

- `class ImageUpdateResponse`

  - **image:** `Image`

### Example

```python
from gradient import Gradient

client = Gradient()
image = client.gpu_droplets.images.update(
    image_id=62137902,
)
print(image.image)
```

## List

`gpu_droplets.images.list(ImageListParams**kwargs)  -> ImageListResponse`

**get** `/v2/images`

To list all of the images available on your account, send a GET request to /v2/images.

## Filtering Results

---

It's possible to request filtered results by including certain query parameters.

**Image Type**

Either 1-Click Application or OS Distribution images can be filtered by using the `type` query parameter.

> Important: The `type` query parameter does not directly relate to the `type` attribute.

To retrieve only ***distribution*** images, include the `type` query parameter set to distribution, `/v2/images?type=distribution`.

To retrieve only ***application*** images, include the `type` query parameter set to application, `/v2/images?type=application`.

**User Images**

To retrieve only the private images of a user, include the `private` query parameter set to true, `/v2/images?private=true`.

**Tags**

To list all images assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your GET request. For example, `/v2/images?tag_name=$TAG_NAME`.

### Parameters

- **page:** `int`

  Which 'page' of paginated results to return.

- **per\_page:** `int`

  Number of items returned per page

- **private:** `bool`

  Used to filter only user images.

- **tag\_name:** `str`

  Used to filter images by a specific tag.

- **type:** `Literal["application", "distribution"]`

  Filters results based on image type which can be either `application` or `distribution`.

  - `"application"`

  - `"distribution"`

### Returns

- `class ImageListResponse`

  - **images:** `List[Image]`

    - **id:** `Optional[int]`

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

    - **created\_at:** `Optional[datetime]`

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

    - **description:** `Optional[str]`

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

    - **distribution:** `Optional[Literal["Arch Linux", "CentOS", "CoreOS", 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.

      - `"Arch Linux"`

      - `"CentOS"`

      - `"CoreOS"`

      - `"Debian"`

      - `"Fedora"`

      - `"Fedora Atomic"`

      - `"FreeBSD"`

      - `"Gentoo"`

      - `"openSUSE"`

      - `"RancherOS"`

      - `"Rocky Linux"`

      - `"Ubuntu"`

      - `"Unknown"`

    - **error\_message:** `Optional[str]`

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

    - **min\_disk\_size:** `Optional[int]`

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

    - **name:** `Optional[str]`

      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[bool]`

      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[List[Literal["ams1", "ams2", "ams3", 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.

      - `"ams1"`

      - `"ams2"`

      - `"ams3"`

      - `"blr1"`

      - `"fra1"`

      - `"lon1"`

      - `"nyc1"`

      - `"nyc2"`

      - `"nyc3"`

      - `"sfo1"`

      - `"sfo2"`

      - `"sfo3"`

      - `"sgp1"`

      - `"tor1"`

      - `"syd1"`

    - **size\_gigabytes:** `Optional[float]`

      The size of the image in gigabytes.

    - **slug:** `Optional[str]`

      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[Literal["NEW", "available", "pending", 2 more]]`

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

      - `"NEW"`

      - `"available"`

      - `"pending"`

      - `"deleted"`

      - `"retired"`

    - **tags:** `Optional[List[str]]`

      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.

    - **type:** `Optional[Literal["base", "snapshot", "backup", 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).

      - `"base"`

      - `"snapshot"`

      - `"backup"`

      - `"custom"`

      - `"admin"`

  - **meta:** `MetaProperties`

    Information about the response itself.

  - **links:** `Optional[PageLinks]`

### Example

```python
from gradient import Gradient

client = Gradient()
images = client.gpu_droplets.images.list()
print(images.images)
```

## Delete

`gpu_droplets.images.delete(intimage_id)`

**delete** `/v2/images/{image_id}`

To delete a snapshot or custom image, send a `DELETE` request to `/v2/images/$IMAGE_ID`.

### Parameters

- **image\_id:** `int`

### Example

```python
from gradient import Gradient

client = Gradient()
client.gpu_droplets.images.delete(
    0,
)
```