API Integration Guide

Wise AI lets you extract vital signs, heart rate and respiratory rate, from a required 60-second video of a person's face. Just send us the video, and we'll return the results in seconds.

Endpoint

POST https://api.wiseai.store/process-video

Authentication

Every request needs an API key passed via the X-API-Key header. Don't have one yet? Reach out to us at contact@wiseai.care to get your API key today.

Making a Request

Send your video as a multipart form upload with the field name file:

curl -X POST https://api.wiseai.store/process-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@video.mp4;type=video/mp4"

Recommended Video Procedure

  1. Ask the subject to face the camera directly with even lighting on the face.
  2. Frame the shot to include the full face and upper chest (important for breathing rate).
  3. Keep the camera stable and record a full 60-second clip with minimal talking or movement.
  4. Export/upload in standard MP4 format and avoid heavy compression.
  5. Submit via the file form field and review confidence scores in the response.

Response

You'll get back a JSON object with the measured vitals, each paired with a confidence score (0 to 1):

{
  "heart_rate": {
    "value": 75.84,
    "confidence": 0.88
  },
  "respiratory_rate": {
    "value": 17.57,
    "confidence": 0.97
  }
}

Field Description

  • heart_rate.value — Estimated heart rate in BPM
  • heart_rate.confidence — Model confidence for the reading
  • respiratory_rate.value — Estimated breaths per minute
  • respiratory_rate.confidence — Model confidence for the reading

Tips for Best Results

Lighting environment

  • Use even illumination across the face and avoid strong side shadows.
  • Avoid flickering light sources and rapidly changing screen light.

Video quality

  • Capture a full 60-second clip; shorter clips may reduce reliability.
  • Prefer clear, higher-bitrate video over heavily compressed clips.
  • You do not need 4K; a clean, stable video is usually better.

Motion and positioning

  • Keep the subject mostly still; normal blinking is fine, but large movement reduces reliability.
  • For respiratory rate, include face + upper chest in frame; face-only is often enough for heart rate.

Validate with confidence

  • Use returned confidence values to flag low-quality captures for retake.

Near Real-Time Vital Sign Monitoring

While the WiseAI API is designed around short video uploads, you can achieve a near real-time experience by adopting a chunked streaming approach for heart rate monitoring.

How It Works

Instead of waiting to collect a full-length video, your client continuously records and dispatches short video segments to the API as they become available. Each chunk is processed independently and returns a result within approximately 2 seconds.

  • Recommended chunk duration: 5 seconds
  • Expected processing time per chunk: ~2 seconds

This means your integration will receive a fresh heart rate reading roughly every 2 seconds, creating a continuously updating display that feels real-time to the end user.

Expected User Experience

Time elapsedWhat the user sees
0 - 7 sNo reading yet (recording + processing first chunk)
~7 sFirst heart rate value appears
Every ~2 s thereafterHeart rate value updates

The initial blank period (typically the first chunk duration plus processing time) is expected behavior and consistent with how real-time biosignal systems work.

Supported Vitals in Chunked Mode

Important: When using the chunked approach, the API returns heart rate only. respiratory_rate is not available from short clips and should be ignored in chunked responses.

Deriving a Final Heart Rate Reading

Because each chunk is processed independently, the values across chunks will vary slightly. To report a stable final heart rate and confidence score, average the heart_rate.value and heart_rate.confidence fields across all chunks collected during the session:

final_hr = sum(chunk["heart_rate"]["value"] for chunk in results) / len(results)
final_confidence = sum(chunk["heart_rate"]["confidence"] for chunk in results) / len(results)

Breathing Rate

The chunked approach does not support respiratory rate. To obtain a breathing rate reading, record and upload a full 60-second video using the standard endpoint. The API will return both heart_rate and respiratory_rate in a single response.

Recommended Integration Pattern

  1. Chunked mode: Split the video feed into 5-second segments and POST each chunk as it is captured. Display the updating heart rate value in your UI. Average results at the end of the session for the final reported value.
  2. Full-video mode: At the end of the session (or as a separate measurement flow), send a full 60-second recording to obtain respiratory rate alongside a consolidated heart rate reading.

Questions or Need Help?

Questions or need help integrating? Contact us at contact@wiseai.care.

Further Reading (rPPG)