Skip to content

Fast Check Crops Endpoint

Faster Pre-cropped face verification. Clients perform face detection locally and send pre-cropped faces, skipping server-side face detection for reduced latency.

In plain terms

If your app already detects faces (e.g., with MediaPipe), send only the cropped face images instead of full frames. This endpoint is faster because the server skips face detection. Each crop must be 224×224 pixels and include context around the face (hair, neck, background)—face should be ~30% of the image.

POST /api/v1/fast-check-crops

Frame requirement

The API requires at least the number of crops required by the selected model (e.g. 10 for mixed-10-v2, 30 for mixed-30-v2). Each crop must be 224×224 PNG. If you send fewer, you will get insufficient_frames. For predictable latency, send exactly frames_required. See Models.

Model selection: v1 vs v2

Flow Header Body What to send
v1 — model model: "mixed-30-v2" (or "10", "mixed-10-v2", etc.)
v2 X-Model-Version frame_count X-Model-Version: latest + frame_count: 30 (10, 60, 90, or 120)

See Model Versioning & Frames for details.

Request Headers

Header Type Required Description
X-Model-Version string No Version alias for v2 model resolution (e.g. latest, v1, v2, fast). When present, use with frame_count in body; model is ignored. See Model Versioning & Frames.

Request Parameters

Parameter Type Required Description
session_id UUID Yes Client-generated unique identifier
model string No Model ID (default: "10"). Recommended: mixed-30-v2. Crop count must meet the model minimum (frames_required). Ignored when X-Model-Version header is present. See Models.
frame_count integer No Number of crops for v2 resolution (10, 30, 60, 90, or 120). Used with X-Model-Version header.
source string No "media" or "live" (default: "media")
crops array Yes Array of pre-cropped face images (224×224 PNG). Must include at least the model's frames_required. For predictable latency, send exactly that many.
bg_segmentation boolean No Optional. Indicates whether background segmentation was applied to crops before sending. Stored in session metadata for analytics.
warnings array No Optional. Capture warnings from frontend. Echoed in response.

Crop Object

Field Type Required Description
index integer Yes Crop sequence number (0-based)
pixels string Yes Base64-encoded 224x224 PNG

Example requests

v1 flow (model in body):

curl -X POST "https://api.moveris.com/api/v1/fast-check-crops" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "mixed-10-v2",
    "source": "live",
    "crops": [
      { "index": 0, "pixels": "iVBORw0KGgoAAAANSUhEUgAA..." },
      { "index": 1, "pixels": "iVBORw0KGgoAAAANSUhEUgAA..." }
    ],
    "bg_segmentation": true
  }'

v2 flow (X-Model-Version + frame_count):

curl -X POST "https://api.moveris.com/api/v1/fast-check-crops" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -H "X-Model-Version: latest" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "frame_count": 10,
    "source": "live",
    "crops": [
      { "index": 0, "pixels": "iVBORw0KGgoAAAANSUhEUgAA..." },
      { "index": 1, "pixels": "iVBORw0KGgoAAAANSUhEUgAA..." }
    ],
    "bg_segmentation": true
  }'

Frame count and optional fields

For mixed-10-v2 (or frame_count: 10) send 10 crops. The examples show 2 for brevity. bg_segmentation is optional; set to true if you applied background segmentation to crops before sending.

Crop Requirements

Original
Frame
→
3x Face
Bounding Box
→
224×224
PNG
  1. Detect face bounding box in original frame
  2. Expand to 3× the face size (square region)
  3. Resize to 224×224 pixels
  4. Export as PNG

Critical: Include context around the face

The crop must include significant context around the face (hair, neck, some background). If the face fills more than 50% of the crop, the model's accuracy degrades significantly.

❌ Too Tight (Wrong)

  • Face fills >50% of crop
  • Little or no context visible
  • May trigger warning in response
  • Accuracy significantly degraded

✅ Correct

  • Face is ~30% of crop
  • Hair, neck, and background visible
  • Optimal context for detection
  • Maximum accuracy achieved

Response Envelope

All responses are wrapped in the standard envelope. The data field contains the verification result on success.

data fields (success 200)

Field Type Description
verdict string "live" or "fake"
confidence float Reserved for future use. Functionally identical to real_score—use real_score for decision-making.
real_score float Raw liveness probability (0.0 - 1.0). Use this field for decision-making.
score float Percentage score (0 - 100) for display
type string Risk band: VERY LOW, LOW, MEDIUM, HIGH, VERY HIGH
session_id UUID Echo of request session_id
model string Model used
input_source string How frames were submitted (rest_crops)
processing_ms integer Processing time in ms
frames_processed integer Number of crops analyzed
tenant_metadata object | null Tenant metadata when applicable
warning string | null Warning if crops appear incorrect
created_at string (ISO 8601) Timestamp when verification result was generated

Example Response with Warning

{
  "data": {
    "verdict": "fake",
    "confidence": 0.85,
    "real_score": 0.15,
    "score": 15.0,
    "type": "VERY LOW",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "mixed-10-v2",
    "input_source": "rest_crops",
    "processing_ms": 420,
    "frames_processed": 10,
    "tenant_metadata": null,
    "warning": "Crop appears too tight (face is 72% of image). Ensure crops include adequate margin around the face (face should be ~30% of crop).",
    "created_at": "2026-03-27T14:00:00Z"
  },
  "success": true,
  "message": "OK"
}

Specifications

Specification Value
Output Size 224 × 224 pixels (square)
Format PNG, base64 encoded
Face Size ~30% of crop area
Expansion Factor 3× the detected face size
Platform Library
JavaScript @mediapipe/tasks-vision - Browser-based face detection
Python mediapipe - Google's MediaPipe face detection

See the Code Examples section for complete implementations.

Postman collection

Import the Moveris API Postman collection to test Fast Check Crops and the rest of the API.