V3 API Reference

• Billing (metered, pay-for-value) — All prediction endpoints now return a billing object in the response. You are only charged when the algorithm returns a valid VHS measurement. Failed predictions, rejected images, and rechecks are always free.
• API Key Security — API keys are now stored as SHA-256 hashes. Raw keys are never stored server-side. Treat your API key like a password — it cannot be recovered if lost.

All endpoints require the x-api-key header. Include your API key with every request:

x-api-key: YOUR_API_KEY

API keys are provisioned per customer. Request an API key.

Returns the current health status of the API service and loaded models.

Response

{
  "status": "healthy",
  "models_loaded": 5,
  "pop_models_loaded": 1,
  "pop_pipeline_enabled": true,
  "model_version": "3.4.0-ensemble"
}

Response Fields

Submit one or more base64-encoded radiograph images for cardiac measurement. Returns VHS, VLAS, landmark coordinates, confidence metrics, and an annotated image.

Request Headers

Single Image Request

{
  "image": "<base64-encoded-image>",
  "uuid": "patient-123",
  "render": true
}

Batch Request (up to 10 images)

{
  "images": ["<base64>", "<base64>"],
  "uuid": "patient-123",
  "render": true
}

Request Fields

Single Image Response

{
  "vhs": 10.4,
  "vlas": 2.8,
  "prediction": [
    { "x": 0.42, "y": 0.15, "class": "heart_top" },
    { "x": 0.41, "y": 0.44, "class": "heart_bottom" },
    { "x": 0.25, "y": 0.30, "class": "heart_right" },
    { "x": 0.57, "y": 0.29, "class": "heart_left" },
    { "x": 0.49, "y": 0.40, "class": "VLAS" },
    { "x": 0.36, "y": 0.12, "class": "Vertebra A" },
    { "x": 0.55, "y": 0.12, "class": "Vertebra B" }
  ],
  "result_code": 1,
  "result_description": "VHS and VLAS predicted successfully with high confidence",
  "model_confidence": "optimal",
  "spread": 0.0032,
  "pop_detected": false,
  "model_version": "3.4.0-ensemble",
  "rendered_image": "<base64-encoded-annotated-image>",
  "historic_vhs": [["2026-03-27", 11.38]],
  "historic_vlas": [["2026-03-27", 1.88]],
  "billing": {
    "billable": true,
    "reason": "valid_vhs",
    "call_type": "single",
    "monthly_usage": 47,
    "tier": "paygo",
    "rate": 3.00
  }
}

Response Fields

Rejection Response

When an image is rejected (result_code 6), the response includes additional fields: classifier_confidence, rejected, and rejection_reason. VHS and VLAS will be null.

{
  "classifier_confidence": 0.7937,
  "model_version": "3.4.0-ensemble",
  "rejected": true,
  "rejection_reason": "not_a_valid_radiograph",
  "result_code": 6,
  "result_description": "Image rejected — not a valid radiograph.",
  "vhs": null,
  "vlas": null,
  "billing": {
    "billable": false,
    "reason": "no_valid_vhs",
    "monthly_usage": 47,
    "tier": "paygo"
  }
}

When an image is rejected, the following standard fields are absent from the response: prediction, model_confidence, spread, pop_detected, rendered_image, historic_vhs, historic_vlas.

Batch Response

{
  "vhs": 11.32,
  "vlas": 1.87,
  "best_photo_index": 0,
  "best_vhs": 11.32,
  "best_vlas": 1.87,
  "median_vhs": 11.32,
  "median_vlas": 1.87,
  "vhs_std": null,
  "vlas_std": null,
  "vhs_confidence": "optimal",
  "vlas_confidence": "optimal",
  "n_photos_processed": 2,
  "n_photos_with_landmarks": 1,
  "processing_started": true,
  "per_photo": [
    {
      "vhs": 11.32,
      "vlas": 1.87,
      "spread": 0.0023,
      "model_confidence": "optimal",
      "landmarks_detected": true,
      "axes_perpendicular": true,
      "pop_detected": false
    },
    {
      "vhs": null,
      "vlas": null,
      "spread": null,
      "model_confidence": "review",
      "landmarks_detected": false,
      "axes_perpendicular": false,
      "rejected": true,
      "rejection_reason": "not_a_valid_radiograph",
      "classifier_confidence": 0.7937
    }
  ],
  "historic_vhs": [["2024-01-26", 9.23]],
  "historic_vlas": [["2024-01-26", 2.12]],
  "model_version": "3.4.0-ensemble",
  "billing": {
    "billable": true,
    "reason": "valid_vhs",
    "call_type": "session",
    "monthly_usage": 48,
    "tier": "paygo",
    "rate": 4.00
  }
}

Batch Response Fields

Error Responses

Submit a batch of images and receive results as Server-Sent Events (SSE). The request body is the same as the batch /v3/predict endpoint.

SSE Events

processing_started

event: processing_started
data: {"n_images": 2, "model_version": "3.4.0-ensemble"}

photo (emitted per image)

event: photo
data: {
  "index": 0,
  "vhs": 11.32,
  "vlas": 1.87,
  "spread": 0.0023,
  "model_confidence": "optimal",
  "landmarks_detected": true,
  "axes_perpendicular": true,
  "n_total": 2,
  "model_version": "3.4.0-ensemble"
}

summary

event: summary
data: {
  "best_vhs": 11.32,
  "best_vlas": 1.87,
  "median_vhs": 11.32,
  "median_vlas": 1.87,
  "vhs_std": null,
  "vlas_std": null,
  "vhs_confidence": "optimal",
  "vlas_confidence": "optimal",
  "best_photo_index": 0,
  "n_photos_processed": 2,
  "n_photos_with_landmarks": 1
}

Billing: Stream predictions are billed at the session rate ($4.00 paygo) as a single event, regardless of how many images are in the batch.

error

event: error
data: {"index": 1, "uuid": "patient-456", "error": "Invalid image data"}

Initialize a new Picture-of-Picture (PoP) capture session. The session guides the client through a multi-frame capture flow to obtain the best possible radiograph image from a screen photo.

Request

Send an empty JSON body:

POST /v3/pop-session/start
Content-Type: application/json
x-api-key: YOUR_API_KEY

{}

Response

{
  "session_id": "0960abaa8179476d",
  "session_status": "ready",
  "pop_pipeline_enabled": true,
  "models_loaded": 5,
  "pop_models_loaded": 1,
  "model_version": "3.4.0-ensemble",
  "session_config": {
    "max_frames": 20,
    "max_consecutive_failures": 5,
    "session_ttl_seconds": 300
  }
}

Response Fields

Send a captured frame to an active PoP session. The server evaluates the frame quality and either requests another frame or completes the session with a prediction.

Request

{
  "image": "<base64-encoded-frame>",
  "session_id": "sess_abc123def456",
  "uuid": "patient-123"
}

Response: Continue — Successful Frame

{
  "session_id": "0960abaa8179476d",
  "session_status": "continue",
  "good_frames": 1,
  "frame_result": {
    "vhs": 10.99,
    "vlas": 1.51,
    "spread": null,
    "model_confidence": "good",
    "landmarks_detected": true,
    "pop_detected": true
  }
}

Response: Continue — Failed Frame

{
  "session_id": "0960abaa8179476d",
  "session_status": "continue",
  "reason": "0/3 good frames so far, need more",
  "frame_index": 0,
  "frames_processed": 1,
  "good_frames": 0,
  "result_code": 5,
  "result_description": "Neither VHS nor VLAS could be calculated — check image quality.",
  "frame_result": {
    "vhs": null,
    "vlas": null,
    "spread": null,
    "model_confidence": "review",
    "landmarks_detected": false,
    "pop_detected": true
  },
  "model_version": "3.4.0-ensemble"
}

No billing field is present during continue — billing is only evaluated on session completion or failure. Note: spread is always null for PoP predictions.

Response: Complete (session succeeded)

{
  "session_id": "sess_abc123def456",
  "session_status": "complete",
  "frame_index": 3,
  "rectified_image": "<base64-encoded-rectified-image>",
  "prediction": {
    "vhs": 10.4,
    "vlas": 2.8,
    "prediction": [
      { "x": 0.42, "y": 0.15, "class": "heart_top" },
      { "x": 0.41, "y": 0.44, "class": "heart_bottom" },
      { "x": 0.25, "y": 0.30, "class": "heart_right" },
      { "x": 0.57, "y": 0.29, "class": "heart_left" },
      { "x": 0.49, "y": 0.40, "class": "VLAS" },
      { "x": 0.36, "y": 0.12, "class": "Vertebra A" },
      { "x": 0.55, "y": 0.12, "class": "Vertebra B" }
    ],
    "result_code": 0,
    "result_description": "Success",
    "model_confidence": "optimal",
    "spread": 0.0028,
    "model_version": "3.4.0-ensemble",
    "rendered_image": "<base64>"
  },
  "billing": {
    "billable": true,
    "reason": "valid_vhs",
    "call_type": "session",
    "monthly_usage": 49,
    "tier": "paygo",
    "rate": 4.00
  }
}

Response: Failed (session could not complete)

{
  "session_id": "sess_abc123def456",
  "session_status": "failed",
  "frame_index": 20,
  "error": "max_frames_exceeded",
  "billing": {
    "billable": false,
    "reason": "no_valid_vhs",
    "monthly_usage": 49,
    "tier": "paygo"
  }
}

A PoP session is billed as a single event at the session rate when it completes with a valid VHS. Failed sessions are never billed.

Session Completion Logic

Detect the four corners of a radiograph screen in a photograph. Returns corner coordinates for use with the /v3/rectify endpoint.

Request

{
  "image": "<base64-encoded-image>"
}

Response

{
  "corners": [[137.48, 100.30], [490.50, 81.32], [495.35, 421.38], [154.89, 421.57]],
  "order": "TL,TR,BR,BL",
  "image_width": 640,
  "image_height": 482,
  "model_version": "3.4.0-ensemble"
}

Response Fields

Apply perspective correction to an image using the provided corner coordinates. Returns a rectified (de-warped) image.

Request

{
  "image": "<base64-encoded JPEG>",
  "corners": [[137.48, 100.30], [490.50, 81.32], [495.35, 421.38], [154.89, 421.57]]
}

Response

{
  "rectified_image": "<base64-encoded JPEG>",
  "width": 346,
  "height": 330,
  "model_version": "3.4.0-ensemble"
}

Combined corner detection and perspective rectification in a single call. Equivalent to calling /v3/corners followed by /v3/rectify.

Request

{
  "image": "<base64-encoded-image>"
}

Response

{
  "rectified_image": "<base64-encoded JPEG>",
  "corners": [[137.48, 100.30], [490.50, 81.32], [495.35, 421.38], [154.89, 421.57]],
  "order": "TL,TR,BR,BL",
  "width": 346,
  "height": 330,
  "model_version": "3.4.0-ensemble"
}

Each prediction returns 7 anatomical landmarks identified on the radiograph. Coordinates are normalized (0.0–1.0) relative to image dimensions.

VHS (Vertebral Heart Score)

The long axis (heart_top to heart_bottom) and short axis (heart_right to heart_left) are measured and mapped onto the thoracic vertebral column starting at T4 (Vertebra A).

VHS = (long_axis_vertebrae + short_axis_vertebrae)

Normal range (canine): 8.5 – 10.5 vertebrae

VLAS (Vertebral Lung-to-Apex Scale)

Distance from heart_top to the VLAS landmark, measured in vertebral units.

VLAS = distance(heart_top, VLAS_landmark) in vertebral units

Normal range (canine): < 2.5 vertebrae. Values ≥ 2.5 suggest left atrial enlargement.

Confidence is determined per-image based on image type. For clean (direct) radiographs, the 5-fold ensemble produces a spread value representing variance between model predictions. For PoP (picture-of-picture) images, a single dedicated model is used and confidence is based on geometry validation and heatmap sharpness. Use model_confidence as the primary confidence indicator for all image types.

Note: spread will be null for PoP predictions. Use model_confidence as the primary confidence indicator.

Clean Radiographs (Ensemble)

PoP Images (Single Model)

Images larger than 1080px on their longest side are automatically downsampled before processing. This ensures consistent performance across different camera resolutions and monitor types. No action required from the client — preprocessing is handled server-side. EXIF orientation data is also automatically applied.

Overview

The V3 API uses pay-for-value billing. You are only charged when the algorithm returns a valid VHS measurement (result codes 1–4). Failed predictions, rejected images, and utility endpoints are always free.

Billing Rules

Pricing Tiers

New API keys default to the pay-as-you-go tier. Contact us for volume pricing or enterprise agreements.

Call Types

Billing Response Object

Three example shapes depending on the billing outcome:

Billable call

{
  "billable": true,
  "reason": "valid_vhs",
  "call_type": "single",
  "monthly_usage": 47,
  "tier": "paygo",
  "rate": 3.00
}

Non-billable call

{
  "billable": false,
  "reason": "no_valid_vhs",
  "monthly_usage": 47,
  "tier": "paygo"
}

Non-billable recheck

{
  "billable": false,
  "reason": "recheck_24h",
  "monthly_usage": 47,
  "tier": "paygo"
}

Billing Response Fields

Tips for Minimizing Costs

1. Always pass uuid — enables 24h recheck grace so repeat scans of the same patient within a day are free.
2. Use batch or stream for multiple images of the same patient — charged once at the session rate instead of per-image.
3. Pre-validate images before sending — ensure images are valid radiographs to avoid wasted requests.

Python — Single Image

import requests
import base64

# Read and encode the radiograph
with open("radiograph.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

# Send prediction request
response = requests.post(
    "https://api.radanalyzer.com/v3/predict",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "image": image_data,
        "uuid": "patient-123",
        "render": True
    }
)

data = response.json()
print(f"VHS: {data['vhs']}")
print(f"VLAS: {data['vlas']}")
print(f"Confidence: {data['model_confidence']}")
print(f"Spread: {data['spread']}")
print(f"Result: {data['result_description']}")

JavaScript — PoP Session Flow

const API_BASE = "https://api.radanalyzer.com";
const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
};

// Step 1: Start a PoP session
const startRes = await fetch(`${API_BASE}/v3/pop-session/start`, {
  method: "POST",
  headers,
  body: JSON.stringify({})
});
const { session_id } = await startRes.json();

// Step 2: Send frames until session completes
let sessionComplete = false;
while (!sessionComplete) {
  const frameBase64 = await captureFrame(); // your capture function

  const frameRes = await fetch(`${API_BASE}/v3/pop-session`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      image: frameBase64,
      session_id: session_id,
      uuid: "patient-123"
    })
  });

  const result = await frameRes.json();

  if (result.session_status === "complete") {
    console.log("VHS:", result.prediction.vhs);
    console.log("VLAS:", result.prediction.vlas);
    sessionComplete = true;
  } else if (result.session_status === "failed") {
    console.error("Session failed:", result.error);
    sessionComplete = true;
  } else {
    console.log("Feedback:", result.feedback);
    // Show feedback to user, capture another frame
  }
}

cURL — Health Check

curl -X GET https://api.radanalyzer.com/v3/health \
  -H "x-api-key: YOUR_API_KEY"