Skip to content

Introduction

The VitalLens API is a web-based service that estimates a person's vital signs from a video of their face and upper body. It uses the same inference engine as our free iOS app VitalLens.

The following vital signs are currently supported:

  • ❤️ Heart rate (HR)
  • 🫁 Respiratory rate (RR)
  • ❤️ Pulse waveform
  • 🫁 Respiratory waveform

It is theoretically possible to also derive heart rate variability (HRV) from the pulse waveform, however we have not yet validated the accuracy of this - such a study is on our roadmap. Our roadmap also includes additional vital signs such as blood oxygen (SpO2) and blood pressure (BP).

Getting access to the VitalLens API

To get your API Key, please visit the API page.

Please first register for an API Key. You will receive an email with a link to verify your account. Once verified, we will automatically generate your unique API Key associated with the free plan. You can then log in on the API page to view your API Key and start using the VitalLens API.

Ways to use the VitalLens API

There are several ways to use the VitalLens API:

  • Python Client: Our Python Client vitallens makes it easy to use the VitalLens API directly from Python. Read the Python Client page to learn more or visit its GitHub Repository.
  • Direct API Calls: Make direct HTTP requests to the VitalLens API from the terminal using tools like curl. This is useful for quick tests or when integrating with non-Python workflows. Read the Direct API Calls page to learn more.

We are working on more ways:

  • JavaScript Client
  • iOS SDK
  • Android SDK

How the VitalLens API works

For each request, the VitalLens API accepts a maximum of 900 frames of spatially downsampled video depicting a single person's face and upper body at resolution 40x40px. This video is passed through our estimation engine, which produces estimates for several vital signs. These estimates are then sent back, after which both the video frames and estimates are disposed of.

What the VitalLens API returns

The returned object for a request to the VitalLens API looks like this:

{
  'face': {
    'confidence': Face live confidence for each frame,
    'note': Explanatory note
  },
  'vital_signs': {
    'heart_rate': {
        'value': Estimated value as float scalar,
        'unit': Value unit,
        'confidence': Estimation confidence as float scalar,
        'note': Explanatory note
    },
    'respiratory_rate': {
      'value': Estimated value as float scalar,
      'unit': Value unit,
      'confidence': Estimation confidence as float scalar,
      'note': Explanatory note
    },
    'ppg_waveform': {
      'data': Estimated waveform value for each frame,
      'unit': Data unit,
      'confidence': Estimation confidence for each frame,
      'note': Explanatory note
    },
    'respiratory_waveform': {
      'data': Estimated waveform value for each frame,
      'unit': Data unit,
      'confidence': Estimation confidence for each frame,
      'note': Explanatory note
    },
  },
  'message': Message about estimates
}

Accuracy of the estimates

TLDR: Estimates have a high degree of accuracy for high-quality video. Each estimate includes an estimation confidence.

We have conducted a study on the Vital Videos dataset with 289 unique participants, showing a mean absolute error for HR at 0.71 bpm and for RR at 0.76 bpm.

For each vital sign estimate, the VitalLens API also produces an estimation confidence between 0% and 100%. When these confidences are lower, this means that accuracies are not as high as the above results - this can be mitigated by ensuring high-quality videos with our guidelines outlined below.

Guidelines to follow for accurate vital signs estimation

To ensure accurate vital signs estimation, follow these guidelines:

  • Minimize camera movement.
  • Keep the subject still and facing the camera.
  • Ensure a bright and steady light source.
  • Video compression can destroy the vitals signal. If you need to encode the video before using the VitalLens API, use as little video compression as possible.

These guidelines are informed by our study in which we investigated how environmental factors such as the above impact estimation accuracy of VitalLens.

Additionally, a good internet connection and sufficient bandwidth are required for optimal performance of the API.

Notes on user privacy and data collection

We do not collect or store any of your video or vital sign estimates data. After returning the API request result, we immediately dispose of this data - hence it is your responsibility to store the returned estimates. Please also see our Terms of Service and Privacy Policy for more information.

Disclaimer

VitalLens is not a medical device and its estimates are not intended for any medical purposes. Please also see our Terms of Service for more information.