API Reference

Use this reference to look up the HTTP and gRPC inference contracts. For a complete deployment walkthrough, start with the Quickstart.

HTTP Endpoints

The release HTTP server exposes the following routes:

The NIM also exposes a binary gRPC API on port 50051 that mirrors the /v1/infer payload as harmonizer.v1.Harmonizer/Process.

API Examples

Use the examples in this section to get started with the API.

The examples use localhost because Docker publishes the port on the client host. For a remote NIM, replace it with the server host name or IP address. From inside Kubernetes, use the Service DNS name. 0.0.0.0 is a server listen address and should not be used as a client destination.

Check Health

Use the following command to check server readiness.

cURL Request

curl -X 'GET' 'http://localhost:8000/v1/health/ready'

Response

{
   "object": "health.response",
   "message": "ready",
   "status": "ready"
}

For the HTTP entrypoint, model loading and startup warmup complete before the server begins accepting connections. During that phase a client normally sees a connection failure or a pending deployment startup probe, not an HTTP 503. After the server is reachable, 200 with "status": "ready" means the backend is ready. A running HTTP server can return 503 if its internal backend readiness state later becomes false.

For the gRPC entrypoint, the model also loads and warms before the gRPC server starts. The standard grpc.health.v1.Health/Check service changes to SERVING after server startup and to NOT_SERVING during shutdown or during the short transition between detecting an unrecoverable CUDA error and terminating the inference process. Its companion HTTP live and ready routes query that gRPC health service. Deployment probes should use /v1/health/ready.

Process Images

Use the process endpoint to enhance one or more images. The images list is ordered: with context_length=4 the list is treated as a frame sequence and the temporal lane builds autoregressive context from previously generated outputs. With context_length=0 each image is processed independently. Each returned image or tensor has the corresponding input’s original dimensions. The runtime stretches the input to 1024x576 for inference and stretches the result back to the original dimensions. Both processing modes are available through either inference transport. A container activates one inference transport at startup, so the HTTP and gRPC tabs below are alternatives rather than simultaneous inference endpoints. See the Quickstart for the corresponding launch commands.

curl -L \
   https://raw.githubusercontent.com/NVIDIA/harmonizer/d1234ff7afb00b6084967dc31b18b526c9b9e7e0/examples/0.png \
   -o input.png
IMAGE_B64="$(base64 < input.png | tr -d '\n')"
curl -X 'POST' \
   'http://localhost:8000/v1/infer' \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   --data-binary @- <<EOF
      {
         "request_id": "demo-0001",
         "images": [
           {
             "id": "frame-000000",
             "data": "${IMAGE_B64}"
           }
         ],
         "parameters": {
           "output_format": "png",
           "context_length": 0,
           "return_policy": "all"
         }
      }
EOF

{
   "request_id": "demo-0001",
   "outputs": [
      {
         "id": "frame-000000",
         "image": {
            "data": "<base64 png>",
            "mime_type": "image/png",
            "width": 1024,
            "height": 576
         },
         "tensor": null
      }
   ]
}

Transport Parameter Values

HTTP represents parameter choices as strings. gRPC represents the same choices as protobuf enums.

Request Fields

The following table describes the request fields:

Raw Tensor Response

For HTTP responses, both image and tensor keys are serialized and exactly one is non-null. gRPC represents the alternatives as a protobuf oneof. With output_format=raw_tensor, HTTP base64-encodes tensor.data and gRPC returns it as bytes. The decoded payload contains tightly packed RGB uint8 values in the [0, 255] range. Output layout is always HWC and output shape is [height, width, 3].

The following HTTP response is for a 1024x576 input:

{
   "request_id": "demo-0001",
   "outputs": [
      {
         "id": "frame-000000",
         "image": null,
         "tensor": {
            "data": "<base64 uint8 RGB bytes>",
            "shape": [576, 1024, 3],
            "layout": "HWC"
         }
      }
   ]
}

Response Fields

The following table describes the response fields:

Model and NIM Information

Use the standard NIM management endpoints rather than inference responses for service and model information. /v1/version reports the release and API versions; /v1/metadata combines version, license, model, and selected-profile information; /v1/models identifies the served model; and /v1/manifest returns the active model manifest. /v1/license returns the packaged license, and /v1/metrics returns Prometheus text rather than JSON.

Error Handling

The HTTP API returns standard status codes to indicate success or failure:

• 200 OK: Request successful
• 400 Bad Request: nimlib request-body validation or invalid input parameters (for example an unsupported context_length or an invalid return_policy for the request shape)
• 503 Service Unavailable: A running backend becomes unavailable
• 500 Internal Server Error: Server-side error

Every HTTP error uses the {"error": ...} envelope shown below. The nested error object always contains the required message, type, and code fields; the OpenAPI schema defines their types.

A missing model artifact normally fails model loading before the HTTP or gRPC server starts, so clients see startup failure rather than an inference response. The current nimlib configuration includes field-specific validation details. For example, setting both image payload fields returns:

{
   "error": {
      "message": "images -> 0: Value error, exactly one of data or tensor must be set",
      "type": "BadRequestError",
      "code": 400
   }
}

The gRPC API uses standard gRPC status codes:

• OK (code 0): The RPC completed successfully
• INVALID_ARGUMENT: Invalid input parameters or malformed payload
• UNAVAILABLE: Model backend is not loaded
• UNKNOWN: Unhandled server-side error

OpenAPI Specification

The HTTP OpenAPI specification is generated from the release nimlib interface and packaged at /opt/nim/api_spec.yaml inside the container. The interactive endpoint reference is available in the API Reference tab.