Skip to content

Live Check Endpoint

Batch liveness detection where the client supplies MediaPipe Face Mesh landmarks (≥468 points) per frame. The server uses those landmarks for face cropping and temporal-physio extraction instead of running its own MediaPipe pass on downsampled crops.

In plain terms

For V3 models, sending landmarks from your own face detector can improve heart-rate and blink-rhythm signals. You still send frame pixels, but each frame also includes the 468-point face mesh. Use this when you already run MediaPipe (or the SDK useSmartFrameCapture with face detection enabled).

POST /api/v1/live-check

v2 upload-first variant

The same landmark requirements apply to POST /api/v2/live-check after uploading frames (with landmarks) via POST /api/v2/upload. See V2 Upload-First Pipeline.

Base URL

https://api.moveris.com

Requirements

  • V3 models only — e.g. mixed-10-v3, mixed-30-v3_1. Other aliases return unsupported_model (400).
  • Landmarks per frame — ≥468 points in normalized [0, 1] coordinates. Accepts [x, y, z] arrays or {x, y, z} objects (MediaPipe JS format).
  • Frame count — Must match the model minimum (e.g. 10 for mixed-10-v3_1).

Basic Flow

1. Generate a session_id (UUID)
2. Capture N frames with MediaPipe Face Mesh landmarks attached to each frame
3. Encode pixels as base64 PNG
4. POST /api/v1/live-check with all frames in one request
5. Receive verdict ("live" or "fake") with real_score

Request Headers

Header Type Required Description
X-API-Key string Yes Your API key
X-Model-Version string No Version alias for v2 model resolution (e.g. latest)

Request body

Field Type Required Description
session_id UUID Yes Unique session identifier
model string No V3 model alias. Ignored when X-Model-Version is set
source string No "media" or "live" (default: "media")
fps float No Capture FPS (default: 30.0)
frames LiveCheckFrame[] Yes Array of frames with pixels and landmarks
frame_count integer No For v2 resolution with X-Model-Version
warnings string[] No Client capture warnings
metadata object No Arbitrary metadata echoed in webhooks

LiveCheckFrame object

Field Type Required Description
index integer Yes Frame sequence number (0-based)
timestamp_ms float Yes Timestamp in milliseconds
pixels string Yes Base64-encoded PNG
landmarks array Yes ≥468 landmark points — [x, y, z] or {x, y, z} per point

Response

Same envelope and verdict fields as Fast Check:

{
  "data": {
    "verdict": "live",
    "real_score": 0.88,
    "score": 88.0,
    "confidence": 0.88,
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "mixed-30-v3_1",
    "processing_ms": 1240,
    "frames_processed": 30
  },
  "success": true,
  "message": "OK"
}

Use real_score for decision-making. See Glossary — Real Score.

SDK usage

// LivenessClient — batch live-check with landmarks on each frame
const result = await client.liveCheck(frames, {
  sessionId: 'uuid-string',
  source: 'live',
  model: 'mixed-30-v3_1',
});

// useLiveness — opt into live-check endpoint
const { start, result } = useLiveness({
  endpoint: 'live-check',
  model: 'mixed-30-v3_1',
});

// useSmartFrameCapture attaches landmarks automatically when FaceLandmarker is ready

Wait for the landmarker (SDK 3.22.4+)

For custom UIs using useSmartFrameCapture with live-check, set requireLandmarks: true so isDetectorReady waits for the FaceLandmarker. Otherwise a short capture (for example 10 frames) can finish before landmarks load and every frame fails server-side face detection.

See LivenessClient and React Hooks.

Errors

Status Code When
400 unsupported_model Model is not a V3 alias
400 insufficient_frames Fewer frames than the model requires
409 session_model_mismatch Reused session_id with a different model

See Errors.