Liveness and Face Match

Verify a returning user by matching a fresh liveness video against a previously enrolled portrait.

• Enroll a reference portrait and match it against live selfie frames
• Send v2 JSON with reference_portrait_b64 plus liveness video
• Gate onboarding on face_match and liveness scores

Time to complete: ~10 minutes

Prerequisites

• SAGEA_API_KEY set in your environment as Bearer auth.
• Read Send your first API request to create a key.
• Read How Helios works to understand liveness and anti-spoofing.
• Test assets: front.jpg, liveness.mp4 (MP4 or MOV or WebM, 3 to 10s), and portrait.jpg (enrolled face).

Step 1: Prepare the portrait and liveness video

Use a clean enrolled portrait and a fresh 3 to 10 second selfie video with one face, good light, and no filters.

ls -lh front.jpg portrait.jpg liveness.mp4
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1 liveness.mp4

Trim or compress to 720p if the video is near the 50MB limit.

Step 2: Send v2 with a reference portrait

POST https://api.sagea.space/helios/kyc/v2 accepts reference_portrait_b64 for 1 to 1 face comparison against liveness frames.

python3 -c "import base64, json; print(json.dumps({'external_id': 'user_12345', 'front_image_b64': base64.b64encode(open('front.jpg','rb').read()).decode(), 'liveness_video_b64': base64.b64encode(open('liveness.mp4','rb').read()).decode(), 'reference_portrait_b64': base64.b64encode(open('portrait.jpg','rb').read()).decode(), 'options': {'store_media': False}}))" > payload.json
 
curl -X POST https://api.sagea.space/helios/kyc/v2 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Helios compares the enrolled portrait to frames sampled from the video and returns face_match plus liveness with anti-spoofing.

Step 3: Gate on face match and liveness

Branch on decision, then apply score thresholds for step-up or retry logic.

curl https://api.sagea.space/helios/verifications/helios_vrf_9f3a2c1e \
  -H "Authorization: Bearer $SAGEA_API_KEY"

A strong match looks like face_match 0.93 and liveness 0.99. A low face match with high liveness usually means the wrong person, not a spoof.

Verify

A successful run returns HTTP 200 with scores for face_match and liveness and a decision. If it fails, check below.

What's next

• Document-only checks
• Step-up re-authentication
• How Helios works