> This page is for NVIDIA Relighting NIM, version 1.1.0.
> For other versions, use one of these documentation indexes:
> - 1.2.0 (Latest) (default): https://docs.nvidia.com/nim/maxine/relighting/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/maxine/relighting/1.1.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/maxine/llms.txt.

# Getting Started

## Prerequisites

To ensure that you have the supported hardware and software stack, check the [Support Matrix](/nim/maxine/relighting/1.1.0/support-matrix).

### NGC Authentication

#### Generate an API Key

An NGC API key is required to access NGC resources. You can generate a key at [https://org.ngc.nvidia.com/setup/api-keys](https://org.ngc.nvidia.com/setup/api-keys).

When creating an NGC API Personal key, ensure that at least **NGC Catalog** is selected from the **Services Included** dropdown. You can include more services if this key is to be reused for other purposes.

<Note>
Personal keys allow you to configure an expiration date, revoke or delete the key using an action button, and rotate the key as needed. For more information about key types, refer to [NGC API Keys](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) in the NGC User Guide.
</Note>

#### Export the NGC API Key

Pass the value of the API key to the `docker run` command in the next section as the `NGC_API_KEY` environment variable to download the appropriate models and resources when starting the NIM.

If you are not familiar with how to create the `NGC_API_KEY` environment variable, the simplest way is to export it in your terminal:

```bash
export NGC_API_KEY=<value>
```

Run one of the following commands to make the key available at startup:

```bash
# If using bash
echo "export NGC_API_KEY=<value>" >> ~/.bashrc

# If using zsh
echo "export NGC_API_KEY=<value>" >> ~/.zshrc
```

<Note>
Other, more secure options include saving the value in a file, so that you can retrieve with `cat $NGC_API_KEY_FILE`, or using a [password manager](https://www.passwordstore.org/).
</Note>

#### Docker Login to NGC

To pull the NIM container image from NGC, first authenticate with the NVIDIA Container Registry with the following command:

```bash
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
```

Use `$oauthtoken` as the username and `NGC_API_KEY` as the password. The `$oauthtoken` username is a special name that indicates that you will authenticate with an API key and not a user name and password.

## Launching the NIM Container

The following command launches the Relighting container with the gRPC service. (For a list of parameters, see [Runtime Parameters for the Container](#runtime-parameters-for-the-container).)

```bash
# Choose manifest profile ID based on target architecture.
export MANIFEST_PROFILE_ID=<enter_valid_manifest_profile_id>
```

Then run the NIM launch command:

```bash
docker run -it --rm --name=relighting-nim \
  --runtime=nvidia \
  --gpus all \
  --shm-size=8GB \
  -e NGC_API_KEY=$NGC_API_KEY \
  -e NIM_MANIFEST_PROFILE=$MANIFEST_PROFILE_ID \
  -e NIM_MAX_CONCURRENCY_PER_GPU=1 \
  -e NIM_HTTP_API_PORT=8000 \
  -e NIM_GRPC_API_PORT=8001 \
  -p 8000:8000 \
  -p 8001:8001 \
  -p 9002:9002 \
  nvcr.io/nim/nvidia/ai4m-relighting:1.1.0
```


<Note>
The flag `--gpus all` is used to assign all available GPUs to the NIM container.
To assign specific GPUs to the NIM container (in case of multiple GPUs available in your machine), use `--gpus '"device=0,1,2..."'`.
</Note>

### Model Manifest Profiles

The following table lists manifest profile IDs that you can specify in `MANIFEST_PROFILE_ID`.

| GPU Architecture (compute capability) | Manifest Profile ID                                              |
| ------------------------------------- | ---------------------------------------------------------------- |
| Blackwell (cc 12.0/10.0)              | 9697136675f0a8998e3b2c5370aba86fc484c05ba64fcb5c068adf72d3282edb |
| Ada (cc 8.9)                          | eb4d86fede4a539a0b1170645e7cddcab1efec9b6ac7dd6091fc73ca4d2a832d |
| Ampere (cc 8.6)                       | 836049b226b20a087b007fbeb6fd7dd4b9e649a2e344cf9632da98e4833ad786 |
| Turing (cc 7.5)                       | 00eba71f1b818164eb4849937de044821184bd7d86e806ba6bebd634259990e6 |

<Note>
`MANIFEST_PROFILE_ID` is an optional parameter. If the manifest profile ID is not supplied, the NIM automatically selects a matching profile ID based on the target hardware architecture.

However, if `MANIFEST_PROFILE_ID` is used, ensure that the associated GPU architecture is compatible with the target hardware. If an incorrect manifest profile ID is used, a deserialization error occurs on inference.
</Note>

If the NIM launch is successful, you get a response similar to the following.

```bash
I0706 19:15:36.358260 61 grpc_server.cc:2558] "Started GRPCInferenceService at 127.0.0.1:9001"
I0706 19:15:36.358384 61 http_server.cc:4704] "Started HTTPService at 127.0.0.1:9000"
I0706 19:15:36.399408 61 http_server.cc:362] "Started Metrics Service at 127.0.0.1:9002"
Triton server is ready
[INFO AI4M BASE LOGGER 2025-07-06 19:15:38.444 base_service.py:serve:241 PID:145] Using threading mode for gRPC service
[INFO AI4M BASE LOGGER 2025-07-06 19:15:38.444 base_service.py:_serve_threading:274 PID:145] Starting threading gRPC service with 1 threads
[INFO AI4M BASE LOGGER 2025-07-06 19:15:38.452 base_service.py:_serve_threading:295 PID:145] Using Insecure Server Credentials
[INFO AI4M BASE LOGGER 2025-07-06 19:15:38.453 base_service.py:_serve_threading:300 PID:145] Listening to 0.0.0.0:8001
```

<Note>
By default, the Relighting gRPC service is hosted on port `8001`. You must use this port for inferencing requests. The port is configurable via the `NIM_GRPC_API_PORT` environment variable.
</Note>

## Environment Variables

The following table describes the environment variables that can be passed into a NIM as a `-e` argument added to a `docker run` command:

| ENV                           | Required? | Default           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------- | --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NGC_API_KEY`                 | Yes       | None              | You must set this variable to the value of your personal NGC API key.                                                                                                                                                                                                                                                                                                                                                               |
| `NIM_CACHE_PATH`              | Optional  | `/opt/nim/.cache` | Location (in container) where the container caches model artifacts.                                                                                                                                                                                                                                                                                                                                                                 |
| `NIM_HTTP_API_PORT`           | No        | `8000`            | HTTP API port inside the container. Serves the following endpoints: `/v1/health/live` (liveness probe), `/v1/health/ready` (readiness probe), `/v1/license` (license information), `/v1/metadata` (asset, license, model, and version metadata), `/v1/manifest` (model manifest), and `/v1/metrics` (Prometheus metrics). Adjust the `-p`/`--publish` flag of `docker run` accordingly (for example, `-p 8000:$NIM_HTTP_API_PORT`). |
| `NIM_GRPC_API_PORT`           | No        | `8001`            | gRPC API port inside the container. Hosts the `VideoRelightingService.Relight` bidirectional streaming RPC and the `grpc.health.v1.Health/Check` health service. Adjust the `-p`/`--publish` flag of `docker run` accordingly (for example, `-p 8001:$NIM_GRPC_API_PORT`).                                                                                                                                                          |
| `NIM_MANIFEST_PROFILE`        | Optional  | None              | You must set this model profile to be able to download the specific model type supported on your GPU. For more about `NIM_MANIFEST_PROFILE`, refer to [Model Manifest Profiles](#model-manifest-profiles).                                                                                                                                                                                                                          |
| `NIM_SSL_MODE`                | No        | disabled          | Set SSL security on the endpoints to `tls` or `mtls`. Defaults to unsecured endpoint.                                                                                                                                                                                                                                                                                                                                               |
| `NIM_SSL_CA_PATH`             | No        | None              | Set the path to the CA root certificate inside the NIM. This is required only when `NIM_SSL_MODE` is `mtls`. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM, `NIM_SSL_CA_PATH` can be set to `/opt/nim/crt/ssl_ca_cert.pem`.                                                                                                                                                                         |
| `NIM_SSL_CERT_PATH`           | No        | None              | Set the path to the server's public SSL certificate inside the NIM. This is required only when an SSL mode is enabled. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM, `NIM_SSL_CERT_PATH` can be set to `/opt/nim/crt/ssl_cert_server.pem`.                                                                                                                                                         |
| `NIM_SSL_KEY_PATH`            | No        | None              | Set the path to the server's private key inside the NIM. This is required only when an SSL mode is enabled. For example, if the SSL certificates are mounted at `/opt/nim/crt` in the NIM, `NIM_SSL_KEY_PATH` can be set to `/opt/nim/crt/ssl_key_server.pem`.                                                                                                                                                                      |
| `NIM_MAX_CONCURRENCY_PER_GPU` | No        | `1`               | Maximum concurrent inference requests per GPU.                                                                                                                                                                                                                                                                                                                                                                                      |

## Runtime Parameters for the Container

| Flags                             | Description                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-it`                             | `--interactive` + `--tty` (see [docker container run](https://docs.docker.com/reference/cli/docker/container/run/)).                                                                                                                                                                                                                                            |
| `--rm`                            | Delete the container after it stops (see [docker container run](https://docs.docker.com/reference/cli/docker/container/run/)).                                                                                                                                                                                                                                  |
| `--name=container-name`           | Give a name to the NIM container. Use any preferred value.                                                                                                                                                                                                                                                                                                      |
| `--runtime=nvidia`                | Ensure NVIDIA drivers are accessible in the container.                                                                                                                                                                                                                                                                                                          |
| `--gpus all`                      | Expose NVIDIA GPUs inside the container. If you are running on a host with multiple GPUs, you need to specify which GPU to use. You can also specify multiple GPUs. For more information about mounting specific GPUs, see [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration). |
| `--shm-size=8GB`                  | Allocate host memory for multi-process communication.                                                                                                                                                                                                                                                                                                           |
| `-e NIM_MAX_CONCURRENCY_PER_GPU`  | Number of concurrent inference requests to be supported by the NIM server per GPU.                                                                                                                                                                                                                                                                              |
| `-e NGC_API_KEY=$NGC_API_KEY`     | Provide the container with the token necessary to download adequate models and resources from NGC. See [NGC Authentication](#ngc-authentication).                                                                                                                                                                                                               |
| `-p <host_port>:<container_port>` | Ports published by the container are directly accessible on the host port.                                                                                                                                                                                                                                                                                      |

## Stopping the Container

The following commands can be used to stop the container.

```bash
docker stop $CONTAINER_NAME
docker rm $CONTAINER_NAME
```