# Image API operations
<a name="pc-py-lib-api-image"></a>

**Topics**
+ [`list_images`](pc-py-lib-api-image-list.md)
+ [`build_image`](pc-py-lib-api-image-build.md)
+ [`delete_image`](pc-py-lib-api-image-delete.md)
+ [`describe_image`](pc-py-lib-api-image-describe.md)

# `list_images`
<a name="pc-py-lib-api-image-list"></a>

```
list_images(image_status, region, next_token)
```

Retrieve the list of existing images.Parameters:

**`image_status` (required)**  
Filters by image status.  
Valid values: `AVAILABLE` \$1 `PENDING` \$1 `FAILED`

**`region`**  
Lists images built in a given AWS Region.

**`next_token`**  
The token for the next set of results.

# `build_image`
<a name="pc-py-lib-api-image-build"></a>

```
build_image(image_configuration, image_id, suppress_validators, validation_failure_level, dry_run, rollback_on_failure, region)
```

Create a custom AWS ParallelCluster image in a given Region.Parameters:

**`image_configuration` (required)**  
The image configuration as Python data.

**`image_id` (required)**  
The image ID.

**`suppress_validators`**  
Identifies one or more image configuration validators to suppress.  
Format: `(ALL | type:[A-Za-z0-9]+)`

**`validation_failure_level`**  
The minimum validation level that causes the image creation to fail. The default is `ERROR`.  
Valid values: `INFO` \$1 `WARNING` \$1 `ERROR`

**`dry_run`**  
If set to `True`, AWS ParallelCluster performs the request validation without creating any resources. You can use this to validate the image configuration. The default is `False`.

**`rollback_on_failure`**  
If set to `True`, AWS ParallelCluster automatically initiates an image stack rollback on failures. The default is `False`.

**`region`**  
The image AWS Region.

# `delete_image`
<a name="pc-py-lib-api-image-delete"></a>

```
delete_image(image_id, region, force)
```

Delete an image in a given Region.Parameters:

**`image_id` (required)**  
The image ID.

**`region`**  
The image AWS Region.

**`force`**  
If set to `True`, AWS ParallelCluster forces deletion if instances are using the AMI or if the AMI is shared. The default is `False`.

# `describe_image`
<a name="pc-py-lib-api-image-describe"></a>

```
describe_image(image_id, region)
```

Get detailed information about an existing image.Parameters:

**`image_id` (required)**  
The image ID.

**`region`**  
The image AWS Region.