> This page is for MAISI, version 1.0.0.
> For other versions, use one of these documentation indexes:
> - 1.0.1 (Latest) (default): https://docs.nvidia.com/nim/medical/maisi/1.0.1/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/medical/maisi/1.0.0/llms.txt

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

# Getting Started

## Setup and Prerequisites

### Hardware Requirements

- Minimum GPU memory (GB): 60 GB for generating images of size 512^3 or larger. Please refer to the [required GPU memory](/nim/medical/maisi/1.0.0/support-matrix#required-gpu-memory) for more details.
- CPU x86-64 >= 8 core (Recommended)
- Memory >= 32 GB (Recommended)
- Minimum Storage: 50 GB (28 GB container size)

### Software Requirements

- Minimum [NVIDIA Driver](https://www.nvidia.com/en-us/drivers/) Version: 535
- Install [Docker](https://docs.docker.com/engine/install/)
- Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#installing-the-nvidia-container-toolkit)

### NGC (NVIDIA GPU Cloud) Account Setup

1. [Create an account on NGC](https://catalog.ngc.nvidia.com/)
2. [Generate an API Key](https://org.ngc.nvidia.com/setup/api-key)
3. Set `NGC_API_KEY`:

    ```bash
    export NGC_API_KEY=<Your NGC API Key>
    ```

4. Docker log in with your NGC API key using `docker login nvcr.io --username='$oauthtoken' --password=$NGC_API_KEY`

### NGC CLI Tool Setup

1. Download the [NGC CLI tool](https://org.ngc.nvidia.com/setup/installers/cli) for your OS.
2. Set up your NGC CLI Tool locally (You'll need your API key for this!):

   ```bash
   ngc config set
   ```

After you enter your API key, you may see multiple options for the org and team. Select as desired or hit enter to accept the default.

## Usage Instructions

### Running NIM

1. Pull the NIM container:

   ```bash
   docker pull nvcr.io/nim/nvidia/maisi:1.0.0
   ```
   

2. Run the NIM container:

   ```bash
   docker run --rm -it --name maisi \
      --runtime=nvidia -e CUDA_VISIBLE_DEVICES=0 \
      -p 8000:8000 \
      -e NGC_API_KEY=$NGC_API_KEY \
      nvcr.io/nim/nvidia/maisi:1.0.0
   ```
   

3. Monitor progress with docker logs:

   ```bash
   docker logs --follow maisi
   ```

### Health and Liveness Checks

- Readiness check:

  ```bash
  curl localhost:8000/v1/health/ready
  ```

- Liveness check:

  ```bash
  curl localhost:8000/v1/health/live
  ```

- Wait for the health check to return status code `200`:

   Bash:

   ```bash
   base_url="http://localhost:8000"
   endpoint="/v1/health/ready"

   response=$(curl -s -o /dev/null -w "%{http_code}" "$base_url$endpoint")

   while [ "$response" -ne 200 ]; do
      echo "Waiting for the service to be ready..."
      sleep 5
      response=$(curl -s -o /dev/null -w "%{http_code}" "$base_url$endpoint")
   done

   echo "Service is ready!"
   ```

   Python:

   ```Python
   import requests
   import time

   base_url = "http://localhost:8000"
   response = requests.get(f"{base_url}/v1/health/ready")

   while response.status_code != 200:
      response = requests.get(f"{base_url}/v1/health/ready")
      
      time.sleep(5)
   print(response.json())
   ```

### Interacting with the API

The MAISI API provides two main endpoints:

1. `/v1/maisi/info`: GET request to retrieve service information
2. `/v1/maisi/run`: POST request to generate synthetic images

Here's a Python script demonstrating how to use the MAISI NIM API to query service information:

```python
import requests
import json

base_url = "http://localhost:8000"

# Query service info
info_response = requests.get(f"{base_url}/v1/maisi/info")
print("Service Info:", json.dumps(info_response.json(), indent=2))
```

And here's a script to generate synthetic images, this script will POST a request to `/v1/maisi/run` with image generation parameters. It then handles the response, saving ZIP files or displaying JSON messages as appropriate.

```python
import requests
from datetime import datetime

base_url = "http://localhost:8000"

# Generate synthetic image
payload = {
    "num_output_samples": 1,
    "body_region": ["abdomen"],
    "anatomy_list": ["liver", "spleen"],
    "output_size": [512, 512, 512],
    "spacing": [1.0, 1.0, 1.0],
    "image_output_ext": ".nii.gz",
    "label_output_ext": ".nii.gz",
}

generation_response = requests.post(f"{base_url}/v1/maisi/run", json=payload)

if generation_response.status_code == 200:
    print("Files generated successfully!")

    if generation_response.headers.get('Content-Type') == 'application/zip':
        # Save ZIP file with timestamp
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        zip_filename = f"output_{timestamp}.zip"
        with open(zip_filename, "wb") as f:
            f.write(generation_response.content)
        print(f"Output saved as {zip_filename}")

    elif 'application/json' in generation_response.headers.get('Content-Type', ''):
        response_json = generation_response.json()
        print("Response:", response_json.get('message') or response_json.get('error'))

    else:
        print("Unexpected response format")
else:
    print(f"Error {generation_response.status_code}: {generation_response.text}")
```

Note: Generating a single 512x512x512 image can take approximately 10 to 20 minutes when using an NVIDIA A100 GPU. The exact time may vary depending on the specific configurations of the system.

#### Stopping the Container

To stop the container, run:

```bash
docker stop maisi
```

## Visualizing the Output

### Example Output

![MAISI result](https://developer.download.nvidia.com/assets/Clara/Images/monai_maisi_ct_generative_example_synthetic_data.png)

### Visualization with 3D Slicer

Users can visualize the MAISI NIM generated segmentation results by viewers of 3D Slicer.
We show a few steps to get started with installing 3D Slicer and visualization of the MAISI segmentation.

#### Install 3D Slicer

To install 3D Slicer, you'll need to download and install stable and preview versions. For more information on installing 3D Slicer, please refer out the [3D Slicer Documentation](https://download.slicer.org/).

- Extract the compressed files, and double click "3D Slicer" application in the file system, select correct version based on different operation systems.

#### Visualization and Rendering

- Open the 3D Slicer app, under launchpad viewer:
- ![3D Slicer Rendering Example 1](/nim/medical/_fern-img/a89f57036f3eda2e27a62e60c4a5dc998de1302ef3a84f6bb58dca762ac096af.webp)

- ![3D Slicer Rendering Example 2](/nim/medical/_fern-img/7efd9bc179ad113c2cc418a2cfa1175c6cd9bf0d43e0de0559b93a2254c37e97.webp)

- Open the MAISI NIM generated CT volume and segmentation file, it can be either NRRD or NIFTI files. Drag the file or import from the menu. In the pop-up window, if you would like to load the file alone, go with the volume option. Or you can select "segmentation" mode.

- Here is an example of the generated CT volume:
- ![3D Slicer Rendering Example 2](/nim/medical/_fern-img/1e1e12357effda6ee93b43234e4b0bbccd2b39bdeaa6bc18e6b59a8b45199f8f.webp)
- Visualize the labels generated, all labels are shown.

- ![3D Slicer Rendering Example 4](/nim/medical/_fern-img/d7b805d4c7eeb9153be1a1730a8bcbd5f1e91e22e1bcfef6b04ea85cc95b28a0.webp)
- Visualize both the CT image and its MAISI labels renderings at the same time. The above figure show the overlay.

## FAQ (Frequently Asked Questions)

1. **Q: What is MAISI and what can it be used for?**  
   A: MAISI (Medical AI for Synthetic Imaging) is a 3D Latent Diffusion Model for generating synthetic CT images. It's primarily used for data augmentation in medical imaging research, helping to supplement limited datasets and enhance the performance of other medical AI models.

2. **Q: Can MAISI be used for clinical purposes?**  
   A: No, MAISI is intended for research purposes only and should not be used for clinical diagnosis or treatment planning.

3. **Q: What are the minimum hardware requirements to run MAISI?**  
   A: MAISI requires a GPU with at least 60 GB of memory for generating images of size 512^3. It has been validated on A100 80GB and H100 GPUs.

4. **Q: How do I specify the anatomical structures I want in the generated images?**  
   A: You can use the `anatomy_list` parameter in the API payload to specify the desired anatomical structures. Refer to the Supported Anatomy table in the API Reference section for a complete list of available options.

5. **Q: Can I control the size of specific organs in the generated images?**  
   A: Yes, you can use the `controllable_anatomy_size` parameter to adjust the size of up to 10 specific organs. The size can be set between 0.0 and 1.0, or -1 to remove the organ.

6. **Q: What output formats does MAISI support?**  
   A: MAISI can output images in NIfTI, DICOM, and Nrrd formats. You can specify the desired format using the `image_output_ext` and `label_output_ext` parameters.

7. **Q: How many images can I generate in a single API call?**  
   A: You can specify the number of images to generate using the `num_output_samples` parameter. There's no fixed limit, but generating a large number of images may take more time and resources.

8. **Q: Is it possible to generate images of different body regions?**  
   A: Yes, you can specify one or more body regions using the `body_region` parameter. Available options include "head", "chest", "thorax", "abdomen", "pelvis", and "lower".

9. **Q: Why am I getting only a part of the body region?**  
    A: This issue may occur if the requested Field of View (FOV) is smaller than the actual body size. Ensure that the `output_size` and `spacing` parameters are correctly set to cover the entire body region. [Here](/nim/medical/maisi/1.0.0/api-reference#recommended-output_size-and-spacing-values) you can find some recommended values for `output_size` and `spacing`.

10. **Q: Why am I getting additional body regions along with the requested one?**  
    A: This issue may occur if the specified Field of View (FOV) is larger than the actual size of the requested body region. Ensure that the `output_size` and `spacing` parameters are accurately set to cover only the desired body region. [Here](/nim/medical/maisi/1.0.0/api-reference#recommended-output_size-and-spacing-values) you can find some recommended values for `output_size` and `spacing`.

11. **Q: How do I handle the API response when generating images?**  
   A: The API response will either be a ZIP file containing the generated images (if successful) or a JSON message (if there's an error or additional information). The provided Python script in the "Interacting with the API" section demonstrates how to handle both types of responses.

12. **Q: How can I report issues or security vulnerabilities related to MAISI?**  
    A: You can report security vulnerabilities or other concerns through the NVIDIA AI Concerns portal at [https://www.nvidia.com/en-us/support/submit-security-vulnerability/](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).

13. **Q: What should I do if the Docker container fails to start?**  
    A: Ensure you have the correct NVIDIA drivers installed (minimum version 535) and the NVIDIA Container Toolkit is properly set up. Also, verify that your system meets the minimum hardware requirements, especially the GPU memory.

14. **Q: What if the health check fails?**  
    A: Wait a few more seconds and try again. If the issue persists, check the docker logs using `docker logs --follow maisi` for any error messages. Ensure your system resources aren't constrained and that the container has full access to the GPU.

15. **Q: What causes an "out of memory" error during image generation?**  
    A: Ensure your GPU has at least 60GB of memory. If not, try reducing the `output_size` parameter or generating fewer samples at a time. You can also try reducing the number of anatomical structures in the `anatomy_list`.

16. **Q: How can I view the generated output files?**  
    A: The output files are in NIfTI, DICOM, or Nrrd format, depending on what you specified. You can use medical imaging software like 3D Slicer, ITK-SNAP, or MRIcroGL to view these files. Ensure the output files were created in the expected location as specified in your API call.

17. **Q: What should I do if the NGC CLI tool setup fails?**  
    A: Double-check that you've entered the correct API key. If issues persist, try regenerating a new API key from the NGC website. Also, ensure you have the latest version of the NGC CLI tool installed.

18. **Q: Can I adjust the generation timeout for large or complex images?**  
    A: Yes, you can set a custom timeout for image generation using the `GENERATE_IMAGE_TIMEOUT` environment variable when starting the Docker container. The default is 1800 seconds (30 minutes).

19. **Q: Is it possible to use a different port for the API server?**  
    A: Yes, you can specify a different API server port using the `NIM_HTTP_API_PORT` environment variable when launching the Docker container. The default port is 8000.

If you encounter any other issues, please refer to the NVIDIA MAISI documentation or reach out to NVIDIA for support.