Model Versioning & Frames Parameters¶

How model aliases work, how to pin versions, and how to send the right frames/crops for each model.

Two ways to select a model¶

The API supports two request flows for model selection. Use one or the other — when the v2 header is present, the model body field is ignored.

Quick reference: v1 vs v2 parameters¶

• v1: model — Alias string (e.g. "mixed-10-v2", "mixed-30-v2", "10"). See common aliases below.
• v2: X-Model-Version — Version alias (latest, v1, v2, fast, etc.). frame_count — One of 10, 30, 60, 90, 120. The API resolves to the concrete model (e.g. latest + 30 → mixed-30-v2).

Example (v2 flow):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "frame_count": 30,
  "source": "live",
  "frames": [ ... ]
}

Header: X-Model-Version: latest

Response headers¶

All responses include X-Moveris-Model-Resolved with the actual model ID used. When the resolved model is deprecated, responses also include:

• Deprecation: true
• Sunset: <ISO-date>
• X-Moveris-Deprecated-Model: <model-id>
• X-Moveris-Suggested-Model: <replacement>

Model aliases (behavior)¶

The model field is an alias that selects the server inference configuration (including the minimum required frames and the model type).

Common aliases¶

What “alias” means¶

• The model you send must be a valid alias (the server validates it).
• The alias determines the frames_required (minimum) that the server uses to validate the request.
• For hybrids (hybrid-v2-*), the server also uses fps to extract consistent temporal signals.

Where to see which models are available¶

• The models registry GET /api/v1/models returns the list of aliases with min_frames and the deprecated flag.
• The React SDK exposes this information via the useModels() hook (that’s why you see activeModels and deprecatedModels).

How the API uses frames (batch endpoints)¶

POST /api/v1/fast-check (frames)¶

For fast-check, the server:

1. Checks that you send enough frames for the model.
2. Runs inference using the decodable frames included in the payload.

Frame count validation

• If you send fewer than frames_required, the API returns error: "insufficient_frames".
• If you send more than frames_required, the API may process extra frames (no strict max is documented); this can increase latency.
• Recommendation: send exactly frames_required for consistent latency and user experience.

index validation

• Each frame includes an index (0-based).
• In fast-check, duplicate index values are rejected (validation fails).
• The API sorts frames by index before processing.

Hybrid models (hybrid-v2-*) and fps¶

If you use a hybrid-v2-* model, the payload includes fps (frames per second) so temporal signal extraction matches your capture.

• fps validates a range of 0 < fps <= 120.
• For non-hybrid models, fps does not change model selection; it is still validated by the request schema.

POST /api/v1/fast-check-crops (crops)¶

For fast-check-crops, the same rule applies:

• With fewer than frames_required crops: error: "insufficient_frames".
• With more than frames_required crops: the API may process additional crops (possible latency increase).
• Recommendation: send exactly frames_required crops.

index validation

• Each crop includes an index (0-based).
• In fast-check-crops, the API sorts crops by index before processing.

fast-check-stream: strict indices¶

In POST /api/v1/fast-check-stream, not only the count matters: the server validates the index of each frame against frames_required.

• frame.index must be within 0..(frames_required - 1).
• If you send a frame.index greater than or equal to frames_required, the API rejects the request with a 400 (detail: “exceeds maximum … for model …”).
• Duplicating a frame.index may be idempotent in the buffer (it does not increment the counter), but the correct flow is to cover all indices from 0 to N-1.

Version Pinning¶

Version pinning is done by explicitly choosing the model alias you want. In practice, that means:

1. Use versioned aliases when available (for example, mixed-30-v2 instead of mixed-30).
2. Avoid aliases marked as deprecated in the models registry.

Examples¶

• Recommended pin: model: "mixed-30-v2" (versioned alias with -v2).
• Migration: model: "mixed-30" (deprecated) -> model: "mixed-30-v2".

Note about the alias 10¶

The alias 10 selects the server’s fast anti-spoofing model, and the implementation may vary depending on internal configuration (for example, the anti-spoofing version used in the deployment).

If you need a strict “v1 vs v2” guarantee for the fast model, coordinate with the Moveris team—there is no additional pinning parameter for 10 on the client side.

Deprecation lifecycle¶

Moveris marks models as deprecated in the models registry. The recommended lifecycle policy is:

• Active (deprecated: false): use as the default.
• Deprecated (deprecated: true): keep compatibility, but migrate as soon as possible.
• Removed: a future phase where a deprecated model may stop being available.

The API and SDK expose that flag:

• GET /api/v1/models includes deprecated per alias.
• useModels() separates activeModels and deprecatedModels.

Migration guide (when deprecations & pinning are in place)¶

1) Migrate mixed-N -> mixed-N-v2¶

1. Replace the model value in your payload:
2. from mixed-30 -> to mixed-30-v2
3. Adjust your frame validation logic using the registry’s min_frames (in these cases it is often the same N, but the registry is the source of truth).

Example (batch payload):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "mixed-30-v2",
  "source": "live",
  "frames": [
    { "index": 0, "timestamp_ms": 0, "pixels": "..." }
  ]
}

2) Migrate your model selector (UI / backend)¶

If your integration today “shows all models”, switch to:

• Use activeModels (non-deprecated) as the primary option.
• Treat deprecatedModels as candidates only if you cannot migrate yet (and show a warning).

If you use the useModels() hook:

• The hook already provides activeModels and deprecatedModels.
• Show deprecatedModels only as a fallback and plan a migration.

3) Ensure correct frame sending¶

• Batch (fast-check / fast-check-crops): send at least frames_required and (recommended) exactly frames_required.
• Stream (fast-check-stream): send frames with frame.index in 0..N-1 for your model.
• Hybrids (hybrid-v2-*): provide real fps (0 < fps <= 120) for consistent capture.

Quick checklist¶

• Choose model using versioned aliases (-v2) when available.
• Do not use deprecated models as the default.
• Validate frames_required against the models registry before capturing.
• Keep frame count and frame indices consistent with the endpoint (batch vs stream).