# Single Inference

Run analysis on a single DICOM image. You can either return base64-encoded images in the response or save output files to disk.

# `POST /single_inference`

This endpoint requires a valid JWT token in the Authorization header. See Authentication.

# Request

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`<your_jwt_token>`

Body (JSON)

{
  "input_image_path": "/path/to/your/dicom/image.dcm",
  "save_to_disk": true,
  "patient_id": "PAT001",
  "output_folder_path": "/path/to/output/folder/"
}

Field	Type	Required	Description
`input_image_path`	`string`	Yes	Absolute path to a single `.dcm` file on the server
`save_to_disk`	`boolean`	Yes	When `true`, save output files to disk. When `false`, return base64 strings in the response
`patient_id`	`string`	No	Optional patient identifier. If provided, it is used in metadata and output folder naming. If omitted, the API uses DICOM `PatientID`
`output_folder_path`	`string`	Conditional	Required when `save_to_disk` is `true`. Absolute path where output files will be saved

# Response

{
  "Result": "Success",
  "Data": {
    "result": "Normal",
    "findings": [],
    "source_image": "/path/to/output/<patient_id>/<patient_id>_source_image.png",
    "heatmap": "/path/to/output/<patient_id>/<patient_id>_heatmap.png",
    "metadata": {
      "model_version": "<string>",
      "patient_id": "<patient_id>",
      "patient_name": "<patient_name>",
      "sop_instance_uid": "<sop_instance_uid>",
      "age": "<age>",
      "sex": "<sex>"
    }
  },
  "Message": "Inference completed successfully."
}

{
  "Result": "Success",
  "Data": {
    "result": "Normal",
    "findings": [],
    "source_image": "<base64_png>",
    "heatmap": "<base64_png>",
    "metadata": {
      "model_version": "<string>",
      "patient_id": "<patient_id>",
      "patient_name": "<patient_name>",
      "sop_instance_uid": "<sop_instance_uid>",
      "age": "<age>",
      "sex": "<sex>"
    }
  },
  "Message": "Inference completed successfully."
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "input_image_path is required in the request"
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "Token missing"
}

{
  "Result": "Failure",
  "Data": null,
  "Message": "Single Inference failed due to an internal error"
}

# Output Files (save_to_disk = true)

On successful inference, the following files are generated inside the output folder under a sub-folder named by the resolved Patient ID:

Request body patient_id, if provided
Otherwise DICOM metadata PatientID

<output_folder_path>/
  └── <patient_id>/
      ├── <patient_id>_predictions.json   # AI prediction results
      ├── <patient_id>_heatmap.png        # Heatmap overlay image
      ├── <patient_id>_source_image.png   # Original image converted to PNG
      └── <patient_id>_report.pdf         # Generated clinical PDF report

# Prediction JSON Structure

The _predictions.json file contains the full inference output:

{
  "result": "TB Presumptive",
  "findings": [
    {
      "name": "Tuberculosis",
      "presence": true,
      "confidence": 0.87
    },
    {
      "name": "Cardiomegaly",
      "presence": false,
      "confidence": 0.12
    },
    {
      "name": "Pleural Thickening",
      "presence": false,
      "confidence": 0.08
    },
    {
      "name": "Pleural Effusion",
      "presence": false,
      "confidence": 0.15
    },
    {
      "name": "Pneumothorax",
      "presence": false,
      "confidence": 0.03
    },
    {
      "name": "Consolidation",
      "presence": true,
      "confidence": 0.72
    },
    {
      "name": "Atelectasis",
      "presence": false,
      "confidence": 0.09
    },
    {
      "name": "Nodule Mass",
      "presence": false,
      "confidence": 0.11
    },
    {
      "name": "Fibrosis",
      "presence": false,
      "confidence": 0.07
    },
    {
      "name": "Infiltration",
      "presence": false,
      "confidence": 0.22
    },
    {
      "name": "Calcification",
      "presence": false,
      "confidence": 0.04
    }
  ],
  "source_image": "C:/output/PAT001/PAT001_source_image.png",
  "heatmap": "C:/output/PAT001/PAT001_heatmap.png",
  "metadata": {
    "model_version": "v1.0.1",
    "patient_id": "PAT001",
    "patient_name": "John Doe",
    "sop_instance_uid": "1.2.840.113619.2.55.3...",
    "age": "045Y",
    "sex": "M"
  }
}

# Notes

If the overall result is Normal, the heatmap field is an empty string.
When save_to_disk is false, source_image and heatmap are base64-encoded PNG strings.

# Validation Rules

Check	Error Code	Message
Missing required fields	`400`	`<field> is required in the request`
Invalid file path	`400`	`Invalid path input_image_path: ...`
File does not exist	`400`	`Input image path does not exist: ...`
File is not `.dcm`	`400`	`Requested image is not a DICOM file: ...`
Cannot read DICOM	`400`	`Invalid DICOM image, unable to fetch patient ID: ...`
Invalid request patient_id	`400`	`Invalid patient_id: '<value>' in request body`
Empty Patient ID	`400`	`Patient ID is empty or None...`
`save_to_disk` not boolean	`400`	`Invalid value for save_to_disk, should be a boolean: ...`
Missing output folder path (save_to_disk=true)	`400`	`output_folder_path is required in the request when save_to_disk is True`
Output folder creation fails	`500`	`Unable to create output folder: ...`

# cURL Example

curl -X POST http://<server-ip>:8500/single_inference \
  -H "Content-Type: application/json" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "input_image_path": "C:/data/patient001.dcm",
    "save_to_disk": true,
    "patient_id": "PAT001",
    "output_folder_path": "C:/output/"
  }'