Skip to content

V2 Upload-First Pipeline

Upload frames during capture, then run inference by session_id without resending pixels. The v2 pipeline is additive — all /api/v1/* endpoints remain unchanged.

In plain terms

Instead of sending all frames in one big request at the end, you upload them in chunks as you capture. When enough frames are buffered server-side, you call a lightweight check endpoint that only needs the session_id. This reduces payload size on the final inference call and pairs well with the React SDK useLivenessV2 hook.

Base URL

https://api.moveris.com

Three-Step Flow

1. Generate a session_id (UUID) for the verification session
2. POST /api/v2/upload — send frames (or a video file) in one or more requests; repeat until is_complete is true
3. POST /api/v2/fast-check OR POST /api/v2/live-check — send session_id only; server resolves frames and returns the verdict

SDK shortcut

Use useLivenessV2 or LivenessView with pipeline="v2" — the SDK handles chunked uploads and the final check call. See React Hooks.

SDK example (manual flow)

// 1. Upload frames in chunks during capture (repeat until is_complete)
await client.v2Upload(frames, {
  sessionId,
  model: 'mixed-30-v3_1',
  source: 'live',
  withLandmarks: true, // required only for the live-check path
});

// 2. Run inference by session_id (no frames in the body)
const result = await client.v2FastCheck({ sessionId, model: 'mixed-30-v3_1' });
// or, for the V3 landmark path:
// const result = await client.v2LiveCheck({ sessionId, model: 'mixed-30-v3_1' });

Step 1 — Upload

POST /api/v2/upload

Buffering only. Stores frames (or extracts them from an uploaded video) keyed by session_id. Never runs inference.

Request body

Provide exactly one of frames (JSON array) or video (multipart file).

Field Type Required Description
session_id UUID Yes Same ID for all upload chunks and the final check call
model string No Model alias (e.g. mixed-30-v3_1). Ignored when X-Model-Version header is present
source string No "media" or "live" (default: "media")
fps float No Video FPS (default: 30.0) — required for hybrid models
frames FrameData[] One of frames/video Batch of frames with index, timestamp_ms, pixels (base64 PNG). Optional landmarks for the live-check path
video file One of frames/video Video file; server extracts frames
frame_count integer No For v2 model resolution with X-Model-Version header (10, 30, 60, 90, or 120)
warnings string[] No Capture warnings from the client

Frame object (upload)

Same as Fast Check Stream, plus optional landmarks for the live-check path:

Field Type Required Description
landmarks array No MediaPipe Face Mesh output — ≥468 [x, y, z] or {x, y, z} points in normalized coordinates. Required only when you plan to call /api/v2/live-check

Upload response

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "frames_received": 10,
    "frames_required": 30,
    "is_complete": false,
    "ttl_seconds": 3600,
    "stored_durable": true
  },
  "success": true,
  "message": "OK"
}
Field Description
frames_received Total frames buffered for this session so far
frames_required Frames needed before inference can run
is_complete true when enough frames are buffered
ttl_seconds How long buffered frames remain available
stored_durable Whether frames were persisted to durable storage

Step 2 — Fast Check (v2)

POST /api/v2/fast-check

Runs inference on frames previously uploaded via /api/v2/upload. The request carries no frame pixels — only session metadata.

Request body

Field Type Required Description
session_id UUID Yes Same ID used during upload
model string No Model alias — must match the upload session
source string No "media" or "live"
fps float No FPS used during capture
frame_count integer No For v2 model resolution with X-Model-Version
warnings string[] No Capture warnings
metadata object No Arbitrary JSON-safe metadata echoed in webhooks as tenant_metadata

Response

Same verdict fields as Fast Check: verdict, real_score, score, confidence, processing_ms, model, session_id, and optional warnings.

Step 2 (alternate) — Live Check (v2)

POST /api/v2/live-check

Same as v2 fast-check, but requires V3 models and frames uploaded with landmarks during the upload step (set withLandmarks: true on v2Upload). See Live Check for landmark requirements.

Model selection

Same v1 vs v2 resolution as other endpoints. See Model Versioning & Frames.

Flow Header Body
v1 (direct) — model: "mixed-30-v3_1"
v2 (header) X-Model-Version: latest frame_count: 30

Idempotency

Reusing a session_id with a different model than the one that produced a cached verdict returns 409 with session_model_mismatch. See Errors.