Skip to content

Direct API Calls

The VitalLens API is a stateless, web-based inference engine that estimates physiological signals from face video. It is the same engine powering our VitalLens iOS App.

You can access the API via a simple HTTP POST request from any language (Python, Node.js, cURL, etc.).

Critical Requirement: You cannot upload raw video

This API is a low-level inference engine. It does not accept standard video files (MP4, MOV) directly.

  • Input: You must crop the video to the face/chest, resize it to exactly 40x40 pixels, and convert it to Raw RGB24 bytes before sending.
  • Output: Heart rate, respiratory rate, HRV (SDNN/RMSSD), and raw waveforms with confidence scores.

See the Preprocessing Guide for the exact formatting rules.

Quickstart Example

This example assumes you have an API key and a video file. It demonstrates the stateless usage (sending a single video clip).

Assets

Download our sample video to test this script.

input_video="sample_video_1.mp4"
api_key="YOUR_API_KEY"

# 1. Crop & Scale (Using ffmpeg)
# We crop to the face/chest and scale to exactly 40x40 pixels.
# The crop coordinates (250:400:335:60) are specific to sample_video_1.mp4.
video=$(ffmpeg -i "$input_video" \
  -vf "crop=250:400:335:60,scale=40:40" \
  -pix_fmt rgb24 -f rawvideo - | base64)

# 2. Extract FPS
# Accurate FPS is required for Heart Rate and HRV calculation.
fps=$(ffprobe -v error -select_streams v:0 \
  -show_entries stream=avg_frame_rate \
  -of default=nw=1:nk=1 "$input_video" \
  | xargs -I {} sh -c 'echo "scale=2; {}" | bc')

# 3. Create Payload
# We request 'process_signals' to get heart rate and respiratory rate.
echo "{\"video\": \"$video\", \"fps\": \"$fps\", \"process_signals\": \"1\"}" > payload.json

# 4. Send Request
# Note: large payloads may take several seconds to process.
curl -X POST \
  -H "x-api-key: $api_key" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json \
  https://api.rouast.com/vitallens-v3/file

Next Steps

  • Check your results: If you get a 200 OK but "unusable" quality, verify your video format in the Preprocessing Guide.
  • Streaming/Long Videos: If you are processing real-time video or long files, read about the state parameter in the API Reference.