# Single Inference

Run AI analysis on a single DICOM image. The endpoint processes the image, generates predictions, a heatmap, and a PDF report — all saved to the specified output folder.

# `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",
  "output_folder_path": "/path/to/output/folder/"
}

Field	Type	Required	Description
`input_image_path`	`string`	Yes	Absolute path to a single `.dcm` DICOM file on the server
`output_folder_path`	`string`	Yes	Absolute path where output files will be saved

# Response

{
  "Result": "Success",
  "Data": null,
  "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

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

<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 AI analysis output:

{
  "result": "TB Presumptive",
  "findings": [
    {
      "name": "Tuberculosis",
      "presence": true,
      "confidence": 0.87
    },
    {
      "name": "Cardiomegaly",
      "presence": false,
      "confidence": 0.12
    },
    {
      "name": "Aortic Enlargement",
      "presence": false,
      "confidence": 0.05
    },
    {
      "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": "/path/to/output/<patient_id>/<patient_id>_source_image.png",
  "heatmap": "/path/to/output/<patient_id>/<patient_id>_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"
  }
}

# Result Categories

The top-level result field indicates the overall assessment:

Result	Meaning
`Normal`	No significant abnormalities detected
`TB Presumptive`	TB detected and supporting abnormalities found in the lungs
`Abnormal But not TB Presumptive`	Abnormalities detected but not indicative of TB

# Validation Rules

The endpoint validates the following before processing:

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: ...`
Empty Patient ID	`400`	`Patient ID is empty or None...`
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": "/data/dicom/patient001.dcm",
    "output_folder_path": "/data/output/"
  }'