Skip to content

Video Detect (Async, Tenant-Scoped)

Submit a pre-recorded video for asynchronous liveness verification, then poll for the result.

In plain terms

Use this when you already have a full video file (for example, uploaded from a mobile app) and do not want to send frames one-by-one. You send the video once, get a submission_id, and check status until processing finishes.

Endpoints

Method Endpoint Purpose
POST /api/v1/{tenant_slug}/video/detect Submit video for async processing
GET /api/v1/{tenant_slug}/video/detect/{submission_id} Poll status and get final result

Authentication and Scopes

  • Header: X-API-Key: sk-...
  • Required scopes:
  • Submit: detection:write
  • Poll: detection:read
  • The API key organization must match tenant_slug (tenant_mismatch otherwise).

Submit Video

POST /api/v1/{tenant_slug}/video/detect

Request

Content type: multipart/form-data

Field Type Required Description
video_file file Conditional Video file upload. Provide exactly one of video_file or video_url.
video_url string Conditional Presigned/public video URL. Provide exactly one of video_file or video_url.
model string No Model alias. Default: mixed-10-v2.
metadata string (JSON object) No Tenant metadata as JSON string. Validated against tenant schema when configured.

Allowed file extensions: mp4, avi, mov, webm, mkv.

cURL Example (file upload)

curl -X POST "https://api.moveris.com/api/v1/acme/video/detect" \
  -H "X-API-Key: sk-your-api-key" \
  -F "video_file=@/path/to/selfie-video.mp4" \
  -F "model=mixed-30-v2" \
  -F 'metadata={"session_type":"onboarding","channel":"mobile"}'

Success Response (201)

All responses are wrapped in the standard envelope.

Field Type Description
submission_id UUID string Unique submission ID used for polling
tenant string Tenant slug from path
status string Always pending on submit
model string Resolved model alias used for this submission
message string Human-readable submission status
tenant_metadata object | null Validated metadata echo
created_at string (ISO 8601) Submission timestamp 
{
  "data": {
    "submission_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "acme",
    "status": "pending",
    "model": "mixed-30-v2",
    "message": "Video submitted for processing. Poll the status endpoint for results.",
    "tenant_metadata": {
      "session_type": "onboarding",
      "channel": "mobile"
    },
    "created_at": "2026-03-27T12:00:00Z"
  },
  "success": true,
  "message": "OK"
}

Poll Submission Status

GET /api/v1/{tenant_slug}/video/detect/{submission_id}

cURL Example

curl -X GET "https://api.moveris.com/api/v1/acme/video/detect/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: sk-your-api-key"

Status Values

  • pending: queued
  • processing: running
  • completed: finished with result
  • failed: finished with error

Completed Response (200)

Field Type Description
submission_id UUID string Submission identifier
tenant string Tenant slug
status string pending, processing, completed, or failed
result object | null Unified verification result when status=completed
tenant_metadata object | null Validated metadata echo
message string | null Human-readable status text
error string | null Error when status=failed
created_at string (ISO 8601) Submission creation timestamp
completed_at string (ISO 8601) | null Completion timestamp

result object fields

Field Type Description
verdict string live or fake
confidence float Confidence (0-1)
real_score float Raw liveness probability (0-1)
score float Percentage score (0-100)
type string VERY LOW, LOW, MEDIUM, HIGH, VERY HIGH
session_id UUID string Mirrors submission_id
model string Model alias used
input_source string video_upload
processing_ms integer Processing time in milliseconds
frames_processed integer Number of frames analyzed
tenant_metadata object | null Metadata echo for correlation
warning string | null Warning message if any
created_at string (ISO 8601) Verification result generation timestamp 
{
  "data": {
    "submission_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant": "acme",
    "status": "completed",
    "result": {
      "verdict": "live",
      "confidence": 0.84,
      "real_score": 0.84,
      "score": 84.0,
      "type": "VERY HIGH",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "model": "mixed-30-v2",
      "input_source": "video_upload",
      "processing_ms": 932,
      "frames_processed": 30,
      "tenant_metadata": {
        "session_type": "onboarding",
        "channel": "mobile"
      },
      "warning": null,
      "created_at": "2026-03-27T12:00:01Z"
    },
    "tenant_metadata": {
      "session_type": "onboarding",
      "channel": "mobile"
    },
    "message": "Processing complete.",
    "error": null,
    "created_at": "2026-03-27T12:00:00Z",
    "completed_at": "2026-03-27T12:00:01Z"
  },
  "success": true,
  "message": "OK"
}

Common Errors

HTTP error Meaning
400 invalid_video_input Missing/duplicated video input, invalid format, or invalid model
400 invalid_metadata Metadata is invalid JSON or fails tenant schema
401 invalid_key Missing/invalid API key
402 insufficient_credits Not enough credits for selected model
403 tenant_mismatch API key does not belong to the requested tenant
404 tenant_not_found / submission_not_found Tenant or submission does not exist
503 service_unavailable Storage/queue/database dependency unavailable

Integration Notes

Polling strategy

Poll every 1-2 seconds with exponential backoff. Stop when status is completed or failed.

Metadata

The API echoes tenant_metadata in both submit and status responses, so you can correlate results in your own systems.

Postman collection

Import the Moveris API Postman collection to test Video Detect (submit and poll) and the rest of the API.