Images

A Genesis Cloud Image can be used to create an Instance. Currently, there are three types of images: base-os, preconfigured and snapshots.

• The base-os images are public basic operating system images, like Ubuntu.
• The cloud-image images are public cloud images like Ubuntu and Debian.
• The preconfigured images are public images with applications or frameworks, like TensorFlow, already installed.
• The snapshot images are backups of instances and are only visible to your account.

Not every image is compatible with all instance types. If an image is incompatible you will receive an error like this one:

{
  "code": "02035",
  "message": "the selected image cannot be run on this instance"
}

Tip: Check on the instance creation flow in the console, if a given instance and image config is supported.

Image Schema

• id String - 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 String - Describes the kind of image. It may be one of base-os, cloud-image, preconfigured, or snapshot.
• family String - Describes the operating system family.
• slug String - The image slug.
• versions Array - The list of versions if this is a cloud-image otherwise empty.
• regions Array - List of region in which this image can be used in, see Regions.
• created_at String - A time value given in ISO8601 combined date and time format that represents when the image was created.

List Images

To list all the images, send a GET request to /compute/v1/images.

GET /compute/v1/images (HTTP 200 - OK)

Query parameters

• type String - An image type name (base-os, cloud-image preconfigured or snapshot) to filter the return list by type.
• per_page Integer _^Optional - A positive integer lower than or equal to 100 indicating the number of items to return per page (default: 50).
• page Integer _^Optional - A positive integer to choose the page to return.

Response body

The response will be a JSON object with pagination details and a key called images. This will be set to an array of image objects, each of which will contain the standard image attributes, see Image Schema:

{
  "images": [
    {
      "id": "df3718d1-c738-49e4-9d44-6b39579a2c6a",
      "type": "cloud-image",
      "family": "Ubuntu ML",
      "slug": "ubuntu-ml-nvidia-pytorch",
      "name": "Ubuntu ML PyTorch for NVIDIA®",
      "os_type": "linux",
      "regions": ["EUC-DE-MUC-1", "NORD-NO-KRS-1"],
      "versions": ["20240308"],
      "created_at": "2024-03-19T16:08:40.235Z",
      "updated_at": "2024-07-05T13:29:29.357Z"
    },
    {
      "id": "3b29b09e-138e-11ef-a299-7fd37e9e8724",
      "type": "cloud-image",
      "family": "Ubuntu",
      "slug": "ubuntu-24.04",
      "name": "Ubuntu 24.04",
      "os_type": "linux",
      "regions": ["NORD-NO-KRS-1"],
      "versions": ["20240423"],
      "created_at": "2024-06-03T10:07:09.366Z",
      "updated_at": "2024-07-05T13:29:29.357Z"
    },
    {
      "id": "2cd0e25f-a39e-4bc6-aa78-b4c40b87072a",
      "type": "cloud-image",
      "family": "Ubuntu",
      "slug": "ubuntu-22.04",
      "name": "Ubuntu 22.04",
      "os_type": "linux",
      "regions": ["NORD-NO-KRS-1"],
      "versions": ["20230927"],
      "created_at": "2023-10-24T08:49:47.816Z",
      "updated_at": "2024-07-05T13:29:29.357Z"
    },
    {
      "id": "55e261aa-f74d-447f-aa0a-c2d39739d995",
      "type": "cloud-image",
      "family": "Debian",
      "slug": "debian-12",
      "name": "Debian 12",
      "os_type": "linux",
      "regions": ["NORD-NO-KRS-1"],
      "versions": ["20240702-1796"],
      "created_at": "2023-10-25T11:22:47.482Z",
      "updated_at": "2024-07-05T13:29:29.357Z"
    }
  ],
  "total_count": 2,
  "page": 1,
  "per_page": 50
}

List all base-os images

To retrieve only base-os images, include the type query parameter set to base-os:

GET /compute/v1/images?type=base-os (HTTP 200 - OK)

List all snapshot images

To retrieve only base-os images, include the type query parameter set to snapshot:

GET /compute/v1/images?type=snapshot (HTTP 200 - OK)

Note that you can get a list of all snapshots with more information in the dedicated snapshots endpoint. Also you can retrieve all snapshots of an instance with more information in the dedicated instance's snapshots endpoint.

Examples (cURL)

# Get all images
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/images"