LivenessClient¶

The LivenessClient class is the core API client for communicating with Moveris API (v2). It wraps all REST endpoints with full TypeScript types, automatic retry with exponential backoff, and configurable error handling.

Import¶

import { LivenessClient } from '@moveris/shared';

Constructor¶

const client = new LivenessClient(config: LivenessClientConfig);

Configuration¶

Example¶

const client = new LivenessClient({
  apiKey: 'sk-your-api-key',
  baseUrl: 'https://api.moveris.com',
  timeout: 30000,
  enableRetry: true,
});

Methods¶

health()¶

Check the API health status.

const status = await client.health();
// Returns: HealthResponse

Returns: HealthResponse with service status and model availability.

getModels()¶

Fetch the list of available models from the API (id, label, description, min_frames, deprecated). Use this for dynamic model selection in your UI. The React SDK provides a useModels hook that wraps this method. Requires a backend proxy that can access the models registry.

const models = await client.getModels();
// Returns: ModelEntry[]

Returns: ModelEntry[] — Array of model entries with id, label, description, min_frames, and deprecated.

fastCheck(frames, options?)¶

Send frames for fast liveness detection with server-side face detection. Frame count must match the model's min_frames (e.g. 10 for mixed-10-v2, 30 for mixed-30-v2).

const result = await client.fastCheck(frames, {
  sessionId: 'uuid-string',
  source: 'live',
  model: '10',
});

Parameters:

Returns: FastCheckResponse with verdict, score, real_score (use this for decision-making), processing_ms, and optionally warnings.

fastCheckCrops(crops, options?)¶

Send 10 pre-cropped 224x224 face images for faster processing.

const result = await client.fastCheckCrops(crops, {
  sessionId: 'uuid-string',
  source: 'live',
});

Parameters:

Returns: FastCheckResponse

streamFrame(frame, options?)¶

Send a single frame for the streaming endpoint. The server buffers frames and processes when all arrive.

const response = await client.streamFrame(frame, {
  sessionId: 'uuid-string',
  source: 'live',
  model: '10',
});

if (response.status === 'buffering') {
  console.log(`${response.frames_received}/${response.frames_required} frames`);
} else if (response.status === 'complete') {
  console.log('Verdict:', response.verdict);
}

Parameters:

Returns: FastCheckStreamResponse with status ("buffering" or "complete"), frames_received, frames_required, and result fields when complete.

fastCheckStream(frames, options?, callbacks?)¶

Send all frames in parallel using the streaming endpoint. This is the lowest-latency option since frames upload simultaneously.

const result = await client.fastCheckStream(
  frames,
  {
    sessionId: 'uuid-string',
    source: 'live',
    model: '10',
  },
  {
    onProgress: (received, total) => {
      console.log(`Progress: ${received}/${total}`);
    },
  }
);

Parameters:

Returns: FastCheckStreamResponse with the final result.

fastCheckStreamSequential(frames, options?, callbacks?)¶

Same as fastCheckStream but sends frames one at a time. Useful for bandwidth-constrained environments.

const result = await client.fastCheckStreamSequential(frames, options, callbacks);

verify(frames, options?)¶

Send 50+ frames for spatial-feature-based verification (standard KYC).

const result = await client.verify(frames, {
  sessionId: 'uuid-string',
  source: 'live',
});

Returns: VerifyResponse

hybridCheck(frames, options?)¶

Send frames for CNN + physiological hybrid analysis.

const result = await client.hybridCheck(frames, {
  sessionId: 'uuid-string',
  source: 'live',
});

Returns: HybridCheckResponse

hybrid50(frames, options?)¶

50-frame hybrid model with 93.8% accuracy.

const result = await client.hybrid50(frames, options);

Returns: HybridCheckResponse

hybrid150(frames, options?)¶

150-frame hybrid model with 96.2% accuracy.

const result = await client.hybrid150(frames, options);

Returns: HybridCheckResponse

getJobResult(jobId)¶

Poll for the result of an asynchronous job.

const status = await client.getJobResult('job-id-string');

Returns: JobStatusResponse with job status and result when complete.

waitForJobResult(jobId, timeout?)¶

Long-poll for a job result. Blocks until the result is ready or the timeout is reached.

const result = await client.waitForJobResult('job-id-string', 60000);

Parameters:

Returns: JobStatusResponse

queueStats()¶

Get queue statistics (pending jobs, processing capacity).

const stats = await client.queueStats();

Returns: QueueStatsResponse

Error Handling¶

All methods throw LivenessApiError on failure:

import { LivenessApiError } from '@moveris/shared';

try {
  const result = await client.fastCheck(frames, options);
} catch (error) {
  if (error instanceof LivenessApiError) {
    console.error('API error:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Error code:', error.code);
  }
}

Common Error Codes¶

Retry Behavior¶

For full error codes and handling, see Errors.

When enableRetry is true (the default), the client automatically retries failed requests with exponential backoff:

• Max attempts: 3
• Initial delay: 1 second
• Max delay: 10 seconds
• Retried errors: Network errors, 5xx server errors, 429 rate limit errors
• Not retried: 4xx client errors (except 429)

Helper Functions¶

The @moveris/shared package also exports utility functions:

import {
  generateSessionId,
  toFrameData,
  toHybridFrameData,
  toLivenessResult,
  toLivenessResultFromStream,
} from '@moveris/shared';

// Generate a UUID session ID
const sessionId = generateSessionId();

// Convert captured frames to API format
const frameData = toFrameData(capturedFrames);