> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# air_sdk.endpoints.images

Stub file for images endpoint type hints.

## Classes

| Name                                                                    | Description                               |
| ----------------------------------------------------------------------- | ----------------------------------------- |
| [`MinimumResources`](#air_sdkendpointsimagesminimumresources)           | None                                      |
| [`ImageShare`](#air_sdkendpointsimagesimageshare)                       | None                                      |
| [`Image`](#air_sdkendpointsimagesimage)                                 | Image model representing a network image. |
| [`ImageEndpointAPI`](#air_sdkendpointsimagesimageendpointapi)           | API client for image endpoints.           |
| [`ImageShareEndpointAPI`](#air_sdkendpointsimagesimageshareendpointapi) | API client for shared image endpoints.    |

## Module Contents

```python
class air_sdk.endpoints.images.MinimumResources
```

```python
cpu: int
```

```python
memory: int
```

```python
storage: int
```

```python
class air_sdk.endpoints.images.ImageShare
```

**Bases**: `air_sdk.air_model.AirModel`

```python
id: str
```

```python
created: datetime.datetime
```

```python
modified: datetime.datetime
```

```python
image: Image
```

```python
image_name: str
```

```python
image_version: str
```

```python
source_org_display_name: str
```

```python
target_org_display_name: str
```

```python
target_org: str
```

```python
expires_at: datetime.datetime
```

```python
claimed_by: str
```

```python
state: str
```

```python
get_model_api() -> type[ImageShareEndpointAPI]
```

```python
model_api: ImageShareEndpointAPI
```

```python
class air_sdk.endpoints.images.Image
```

**Bases**: `air_sdk.air_model.AirModel`

Image model representing a network image.

```python
id: str
```

Unique identifier for the image

```python
name: str
```

Human-readable name of the image

```python
version: str
```

Version of the image

```python
created: datetime.datetime
```

Timestamp when the image was created

```python
creator: str
```

User who created the image

```python
modified: datetime.datetime
```

Timestamp when the image was last modified

```python
mountpoint: str | None
```

Mountpoint of the image

```python
minimum_resources: MinimumResources
```

Minimum resources required to run the image

```python
includes_air_agent: bool
```

Whether the image includes the Air agent

```python
cpu_arch: str
```

CPU architecture of the image

```python
default_username: str
```

Default username for the image

```python
default_password: str
```

Default password for the image

```python
emulation_type: list[str]
```

The types of emulation the image supports

```python
emulation_version: str
```

The version of the emulation the image supports

```python
provider: str
```

Provider of the image

```python
published: bool
```

Whether the image is published

```python
upload_status: str
```

Status of the image upload

```python
last_uploaded_at: datetime.datetime | None
```

Timestamp when the image was last uploaded

```python
size: int
```

Size of the image

```python
hash: str
```

Hash of the image

```python
is_owned_by_client: bool
```

Whether the image is owned by the client

```python
get_model_api() -> type[ImageEndpointAPI]
```

```python
model_api: ImageEndpointAPI
```

```python
update(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...,
    default_username: str | dataclasses._MISSING_TYPE = ...,
    default_password: str | dataclasses._MISSING_TYPE = ...,
    mountpoint: str | None | dataclasses._MISSING_TYPE = ...,
    cpu_arch: str | dataclasses._MISSING_TYPE = ...,
    includes_air_agent: bool | dataclasses._MISSING_TYPE = ...,
    emulation_type: list[str] | dataclasses._MISSING_TYPE = ...,
    emulation_version: str | dataclasses._MISSING_TYPE = ...,
    provider: str | dataclasses._MISSING_TYPE = ...
) -> None
```

Update the image's properties.

**Example:**

```python
>>> image.update(name='new-name', version='1.0.0')
>>> image.update(default_username='user', default_password='pass')
```

**Parameters:**

* `name` – Name of the image
* `version` – Version of the image
* `default_username` – Default username for the image
* `default_password` – Default password for the image
* `mountpoint` – Mountpoint of the image
* `cpu_arch` – CPU architecture of the image
* `includes_air_agent` – Whether the image includes the Air agent
* `emulation_type` – The types of emulation the image supports
* `emulation_version` – The version of the emulation the image supports
* `provider` – Provider of the image

```python
upload(
    *,
    filepath: str | pathlib.Path,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image
```

Upload the image to the Air platform.

All uploads use multipart upload to S3. Parts are \~100MB each,
calculated automatically by the API.

**Parameters:**

* `filepath` – local file path to the image
* `timeout` – Timeout per part upload (default: DEFAULT\_UPLOAD\_TIMEOUT).
* `max_workers` – number of concurrent workers for parallel uploads (default: 1 for sequential).

**Example:**

```python
>>> image.upload(filepath='local_file_path')
```

**Returns:**

the uploaded image instance

```python
clear_upload() -> Image
```

Clear the upload status of the image.

**Example:**

```python
>>> image.clear_upload()
```

**Returns:**

the image instance

```python
publish(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image
```

Publish the image.

**Parameters:**

* `name` – new name of the image
* `version` – new version of the image

**Example:**

```python
>>> image.publish()
>>> image.publish(name='new-name', version='1.0.0')
```

**Returns:**

the published image instance

```python
unpublish(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image
```

Unpublish the image.

**Parameters:**

* `name` – new name of the image
* `version` – new version of the image

**Example:**

```python
>>> image.unpublish()
>>> image.unpublish(name='new-name', version='1.0.0')
```

**Returns:**

the image instance

```python
share(
    *,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare
```

Share the image with another organization.

**Parameters:**

* `target_org` – The NGC org name of the organization receiving the image
* `expires_at` – The date and time the image share expires

**Example:**

```python
>>> share = image.share(target_org='target-org-name')
```

**Returns:**

The created share instance

```python
class air_sdk.endpoints.images.ImageEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.images.Image]`

API client for image endpoints.

```python
API_PATH: str
```

```python
model: type[Image]
```

```python
create(
    *,
    name: str,
    version: str,
    default_username: str,
    default_password: str,
    mountpoint: str | None | dataclasses._MISSING_TYPE = ...,
    cpu_arch: str | dataclasses._MISSING_TYPE = ...,
    includes_air_agent: bool | dataclasses._MISSING_TYPE = ...,
    emulation_type: list[str] | dataclasses._MISSING_TYPE = ...,
    emulation_version: str | dataclasses._MISSING_TYPE = ...,
    provider: str | dataclasses._MISSING_TYPE = ...,
    filepath: str | pathlib.Path | dataclasses._MISSING_TYPE = ...,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image
```

Create a new image.

**Parameters:**

* `name` – Name of the image
* `version` – Version of the image
* `default_username` – Default username for the image
* `default_password` – Default password for the image
* `mountpoint` – Mountpoint of the image
* `cpu_arch` – CPU architecture of the image
* `includes_air_agent` – Whether the image includes the Air agent
* `emulation_type` – The types of emulation the image supports
* `emulation_version` – The version of the emulation the image supports
* `provider` – Provider of the image
* `filepath` – Optional path to image file. If provided, uploads the image after creation using upload.
* `timeout` – Timeout per part upload (default: DEFAULT\_UPLOAD\_TIMEOUT). Only used if filepath is provided.
* `max_workers` – Number of concurrent workers for parallel uploads (default: 1). Only used if filepath is provided.

**Example:**

```python
>>> # Create image without upload
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
... )

>>> # Create and upload image in single step
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
...     filepath='./cumulus-vx.qcow2',
... )

>>> # Create and upload with parallel workers
>>> api.images.create(
...     name='cumulus-vx-1.2.3',
...     version='1.0.0',
...     default_username='user',
...     default_password='password',
...     filepath='./large-image.qcow2',
...     max_workers=4,
... )
```

**Returns:**

The created Image instance

```python
list(
    *,
    name: str = ...,
    version: str = ...,
    cpu_arch: Literal[x86, ARM] = ...,
    creator: str = ...,
    includes_air_agent: bool = ...,
    provider: Literal[VM, CONTAINER] = ...,
    published: bool = ...,
    upload_status: Literal[READY, UPLOADING, VALIDATING, COMPLETED, PUBLISHED, UNPUBLISHED, UNPUBLISHING, COPYING_FROM_IMAGE_SHARE] = ...,
    hash: str = ...,
    is_owned_by_client: bool = ...,
    limit: int = ...,
    offset: int = ...,
    ordering: str = ...,
    search: str = ...
) -> Iterator[Image]
```

List all images with optional filtering.

**Parameters:**

* `name` – Name of the image
* `version` – Version of the image
* `cpu_arch` – CPU architecture of the image
* `creator` – Creator of the image
* `includes_air_agent` – Whether the image includes the Air agent
* `emulation_type` – The types of emulation the image supports
* `emulation_version` – The version of the emulation the image supports
* `provider` – Provider of the image
* `published` – Whether the image is published
* `upload_status` – Status of the image upload
* `last_uploaded_at` – Timestamp when the image was last uploaded
* `hash` – Hash of the image
* `is_owned_by_client` – Whether the image is owned by the client
* `limit` – Maximum number of results to return
* `offset` – Offset for pagination
* `ordering` – Ordering of the results
* `search` – Search query

**Example:**

```python
>>> for image in api.images.list():
...     print(image.name)

>>> # Filter by name
>>> for image in api.images.list(search='image-name'):
...     print(image.name)

>>> # Order by name descending
>>> for image in api.images.list(ordering='-name'):
...     print(image.name)
```

**Returns:**

Iterator of Image instances

```python
get(pk: PrimaryKey) -> Image
```

Get a specific image by ID.

**Parameters:**

* `pk` – The image ID (string or UUID)

**Example:**

```python
>>> image = api.images.get('image-id')
```

**Returns:**

The Image instance

```python
upload(
    *,
    image: Image | PrimaryKey,
    filepath: str | pathlib.Path,
    timeout: datetime.timedelta | None | dataclasses._MISSING_TYPE = ...,
    max_workers: int | dataclasses._MISSING_TYPE = ...
) -> Image
```

Upload the image to the Air platform.

All uploads use multipart upload to S3. Parts are \~100MB each,
calculated automatically by the API.

**Parameters:**

* `image` – Image instance or image ID
* `filepath` – Path to the file to upload
* `timeout` – Timeout per part upload (default: DEFAULT\_UPLOAD\_TIMEOUT). This timeout applies to EACH part upload (not total operation).
* `max_workers` – Number of concurrent workers for uploads. Default: 1 (sequential uploads). Set \> 1 for parallel uploads.

**Returns:**

Updated Image instance

**Example:**

```python
>>> # File upload
>>> image.upload(filepath='image.qcow2')

>>> # Large file with parallel upload
>>> image.upload(filepath='large.qcow2', max_workers=4)
```

**Raises:**

* `FileNotFoundError` – If the file does not exist
* `ValueError` – If filepath is not a regular file or max\_workers \< 1
* `PermissionError` – If the file is not readable
* `AirUnexpectedResponse` – If upload fails or backend returns invalid data
* `requests.RequestException` – For network/HTTP errors

```python
clear_upload(
    *,
    image: Image | PrimaryKey
) -> None
```

Clear the upload status of the image.

**Parameters:**

* `image` – image to clear upload

**Example:**

```python
>>> api.images.clear_upload(image)
```

**Returns:**

None

```python
publish(
    *,
    image: Image | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image
```

Publish the image.

**Args:**

Required parameters:
image: image to publish

Optional Parameters:
name: The name of the image
version: The version of the image

**Returns:**

None

**Example:**

```python
>>> api.images.publish(image)
```

```python
unpublish(
    *,
    image: Image | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image
```

Unpublish the image.

**Parameters:**

* `image` – image to unpublish (Image instance or image ID)
* `name` – new name of the image
* `version` – new version of the image

**Example:**

```python
>>> api.images.unpublish(image)
>>> api.images.unpublish(image, name='new-name', version='new-version')
```

**Returns:**

the unpublished image instance

```python
share(
    *,
    image: Image | PrimaryKey,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare
```

Share the image with another organization.

**Args:**

Required parameters:
image: The image to share (Image instance or image ID)
target\_org: The NGC org name of the organization receiving the image

Optional parameters:
expires\_at: The date and time the image share expires

**Returns:**

ImageShare: The created share object

**Example:**

```python
>>> share = api.images.share(image='image-id', target_org='target-org-name')
```

```python
claim_image_share(
    *,
    image_share: PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    version: str | dataclasses._MISSING_TYPE = ...
) -> Image
```

Claim a shared image into your organization.

**Parameters:**

* `image_share` – The share ID to claim (string or UUID)
* `name` – new name of the image
* `version` – new version of the image

**Example:**

```python
>>> image = api.images.claim_image_share(image_share='share-id')
>>> image = api.images.claim_image_share(
...     image_share='share-id', name='new-name', version='1.0.0'
... )
```

**Returns:**

The claimed image

```python
shares: ImageShareEndpointAPI
```

Access the image shares API.

**Returns:**

ImageShareEndpointAPI: The API for managing image shares

**Example:**

```python
>>> # List all shared images
>>> for share in api.images.shares.list():
...     print(share.image_name)

>>> # Create a new share
>>> share = api.images.shares.create(
...     image='image-id',
...     target_org='target-org-name',
... )

>>> # Get a specific share
>>> share = api.images.shares.get('share-id')

>>> # Delete a share
>>> api.images.shares.delete('share-id')
```

```python
class air_sdk.endpoints.images.ImageShareEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.images.ImageShare]`

API client for shared image endpoints.

```python
API_PATH: str
```

```python
model: type[ImageShare]
```

```python
list(
    *,
    limit: int | dataclasses._MISSING_TYPE = ...,
    offset: int | dataclasses._MISSING_TYPE = ...,
    ordering: str | dataclasses._MISSING_TYPE = ...,
    search: str | dataclasses._MISSING_TYPE = ...
) -> Iterator[ImageShare]
```

List all shared images.

**Parameters:**

* `limit` – Maximum number of results to return
* `offset` – Offset for pagination
* `ordering` – Ordering of the results
* `search` – Search query

**Example:**

```python
>>> # List all shared images
>>> for share in api.images.shares.list():
...     print(share.image_name)

>>> # Filter by image name
>>> for share in api.images.shares.list(search='image-name'):
...     print(share.image_name)

>>> # Order by image name descending
>>> for share in api.images.shares.list(ordering='-image_name'):
...     print(share.image_name)
```

**Returns:**

Iterator of ImageShare instances

```python
create(
    *,
    image: Image | PrimaryKey,
    target_org: str,
    expires_at: datetime.datetime | dataclasses._MISSING_TYPE = ...
) -> ImageShare
```

Create a new image share.

**Parameters:**

* `image` – The image or image ID to share
* `target_org` – The NGC org name of the organization receiving the image
* `expires_at` – The date and time the image share expires

**Example:**

```python
>>> share = api.images.shares.create(
...     image='image-id', target_org='target-org-name'
... )
```

**Returns:**

The created image share instance

```python
get(pk: PrimaryKey) -> ImageShare
```

Get a specific shared image by ID.

**Parameters:**

* `pk` – The image share ID (string or UUID)

**Example:**

```python
>>> share = api.images.shares.get('share-id')
```

**Returns:**

The ImageShare instance

```python
delete(pk: PrimaryKey) -> None
```

Delete (unshare) an image share.

**Parameters:**

* `pk` – The share ID to delete (string or UUID)

**Example:**

```python
>>> api.images.shares.delete('share-id')
>>> api.images.shares.delete(share.id)
```

**Returns:**

None