Fast Check Stream Endpoint¶
Liveness verification by sending one frame per request. You send N frames sequentially (N depends on model — e.g. 10 for mixed-10-v2, 30 for mixed-30-v2); the API buffers them and returns the verdict when the last frame arrives. Ideal when capturing frames in real time (e.g. from a camera stream).
In plain terms
Instead of sending all frames in one request, you send them one by one. Use the same session_id for all frames. The API buffers them and returns the live/fake verdict when the final frame (count depends on model) arrives. Best for real-time camera capture.
POST
/api/v1/fast-check-stream Base URL¶
Basic Flow¶
1. Generate a session_id (UUID) for the verification session
2. Capture N video frames (N = model's frames_required, e.g. 10 for mixed-10-v2, 30 for mixed-30-v2)
3. Encode each frame as base64 PNG
4. Send each frame in a separate POST to /api/v1/fast-check-stream (same session_id, same model)
5. On the final frame, the API returns the verdict ("live" or "fake") with confidence score
Stream vs single request
Unlike /api/v1/fast-check (which sends all frames in one JSON body), this endpoint receives one frame per POST. Use the same session_id and model for all requests. The verdict is returned only in the response to the last frame.
Model selection: v1 vs v2¶
| Flow | Header | Body | What to send |
|---|---|---|---|
| v1 | — | model | model: "mixed-30-v2" (or "10", "mixed-10-v2", etc.) — same for every frame |
| v2 | X-Model-Version | frame_count | X-Model-Version: latest + frame_count: 30 — same for every frame in the session |
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; must be the same for all requests |
model | string | No | Model ID (e.g. mixed-10-v2, mixed-30-v2). Frame count must match the model. Ignored when X-Model-Version header is present. See Models. |
frame_count | integer | No | Number of frames for v2 resolution (10, 30, 60, 90, or 120). Used with X-Model-Version header; must be consistent across all requests in the session. |
source | string | No | "media" or "live" (default: "media") |
frame | object | Yes | Single frame object (one per request) |
warnings | array | No | Optional. Per-frame capture warnings (e.g. "Low light detected"). Aggregated and echoed in final response. |
Frame Object¶
| Field | Type | Required | Description |
|---|---|---|---|
index | integer | Yes | Frame sequence number (0-based, max depends on model) |
timestamp_ms | float | Yes | Timestamp in milliseconds |
pixels | string | Yes | Base64-encoded image (PNG recommended) |
Response Envelope¶
All responses are wrapped in the standard envelope. The data field contains the buffering status or verdict result.
Frames 1 to N-1: buffering response. Frame N: full verdict response (N = model's frames_required).
Buffering (frames 1 to N-1)¶
| Field | Type | Description |
|---|---|---|
status | string | "buffering" while waiting for remaining frames |
session_id | UUID | Echo of request session_id |
frames_received | integer | Number of frames received so far in this session |
frames_required | integer | Total frames required for the selected model |
ttl_seconds | integer | Remaining buffer TTL bucket for this session |
warnings | array | null | Per-frame warnings if provided; null otherwise |
Final (frame N)¶
| 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 |
session_id | UUID | Echo of request session_id |
model | string | Model used for this request |
processing_ms | integer | Server processing time in milliseconds |
frames_processed | integer | Number of frames analyzed (matches model) |
frames_received | integer | Frames received in this session |
available | boolean | Whether the service is available |
warning | string | null | Warning message if any |
warnings | array | null | Aggregated capture warnings from all frames |
error | string | null | Error message if any |
Final response metadata¶
| Field | Type | Description |
|---|---|---|
status | string | "complete" when processing has finished |
frames_required | integer | Total frames required for this model |
ttl_seconds | integer | 0 after completion (buffer cleaned up) |
Examples¶
Single frame request (e.g. frame 0) — v1 flow¶
curl -X POST "https://api.moveris.com/api/v1/fast-check-stream" \
-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",
"frame": {
"index": 0,
"timestamp_ms": 0,
"pixels": "iVBORw0KGgoAAAANSUhEUgAA..."
}
}'
Single frame request — v2 flow (X-Model-Version + frame_count)¶
curl -X POST "https://api.moveris.com/api/v1/fast-check-stream" \
-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",
"frame": {
"index": 0,
"timestamp_ms": 0,
"pixels": "iVBORw0KGgoAAAANSUhEUgAA..."
}
}'
Consistency
When using v2 flow, send the same frame_count and X-Model-Version header for every frame in the session.
Response while buffering (frames 1–9)¶
{
"data": {
"status": "buffering",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"frames_received": 1,
"frames_required": 10,
"ttl_seconds": 60,
"warnings": null
},
"success": true,
"message": "OK"
}
Response on 10th frame (verdict)¶
{
"data": {
"status": "complete",
"verdict": "live",
"confidence": 0.95,
"real_score": 0.95,
"score": 95.0,
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"model": "mixed-10-v2",
"processing_ms": 245,
"frames_processed": 10,
"frames_received": 10,
"frames_required": 10,
"ttl_seconds": 0,
"available": true,
"warning": null,
"warnings": null,
"error": null
},
"success": true,
"message": "OK"
}
JavaScript: send 10 frames sequentially¶
// Send 10 frames sequentially (same session_id)
const sessionId = crypto.randomUUID();
const frameCount = 10;
// Assume getFrame(i) returns { index, timestamp_ms, pixels } from camera
for (let i = 0; i < frameCount; i++) {
const frame = getFrame(i);
const res = await fetch('https://api.moveris.com/api/v1/fast-check-stream', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'sk-your-api-key',
// Optional v2 flow: use X-Model-Version + frame_count instead of model
// 'X-Model-Version': 'latest',
},
body: JSON.stringify({
session_id: sessionId,
model: 'mixed-10-v2',
// frame_count: frameCount, // Use with X-Model-Version for v2 flow
source: 'live',
frame: {
index: frame.index,
timestamp_ms: frame.timestamp_ms,
pixels: frame.pixels,
},
}),
});
const envelope = await res.json();
const data = envelope.data;
if (data.verdict) {
console.log('Verdict:', data.verdict, 'Score:', data.score);
break; // last frame: verdict is ready
}
console.log('Buffering:', data.frames_received);
}
Postman collection
Import the Moveris API Postman collection to call every endpoint, including this one. The stream requests send frames sequentially and assert frames_received and the final verdict.