Model Versioning & Frames Parameters

How Mixed V3.1.1 aliases work, how to pin a version, and how many frames to send.

In plain terms

Send model: "mixed-30-v3_1_1" (or 60 / 120) and exactly that many frames. latest in the version header also resolves to V3.1.1.

Two ways to select a model

Use one flow or the other. When X-Model-Version is present, the model body field is ignored.

Quick reference

Flow	Request header	Body parameter	Required	Example
v1	(none)	model	No (default: mixed-30-v3_1_1)	model: "mixed-30-v3_1_1"
v2	X-Model-Version	frame_count	Both together	X-Model-Version: latest + frame_count: 30

• v1: model — mixed-30-v3_1_1, mixed-60-v3_1_1, or mixed-120-v3_1_1.
• v2: X-Model-Version — latest or v3_1_1. frame_count — 30, 60, or 120.

Client	Header	Body	Resolves to
v1	—	model: "mixed-30-v3_1_1"	mixed-30-v3_1_1
v2	X-Model-Version: latest	frame_count: 30	mixed-30-v3_1_1
v2	X-Model-Version: v3_1_1	frame_count: 120	mixed-120-v3_1_1

Version aliases for X-Model-Version

Version alias	Resolves to	Valid frame_count values
latest	Mixed V3.1.1 (mixed-N-v3_1_1)	30, 60, 120
v3_1_1	Mixed V3.1.1 (mixed-N-v3_1_1)	30, 60, 120

frame_count must be 30, 60, or 120

A frame_count outside 30, 60, or 120 returns 400. Pin the explicit alias in model if you are unsure.

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

Alias	Frames required	Default?
mixed-30-v3_1_1	30	Yes
mixed-60-v3_1_1	60	No
mixed-120-v3_1_1	120	No

The alias sets frames_required. Send at least that many consecutive frames — exactly that many for predictable latency.

Where to see which models are available

• GET /api/v1/models returns aliases with min_frames and deprecated.
• The React SDK exposes the same list through useModels() (activeModels / deprecatedModels).
• The compile-time SDK catalog is MODEL_CONFIGS in @moveris/shared (the three V3.1.1 aliases only).

How the API uses frames

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

1. Checks that you send enough frames for the model.

2. Runs inference on the decodable frames in the payload.

3. Fewer than frames_required → insufficient_frames.

4. More than frames_required may be processed and can increase latency. Send exactly frames_required.
5. Each frame has a 0-based index. Duplicate indices are rejected. The API sorts by index.

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

Same count rule as fast-check. Each crop is a 224×224 PNG. Duplicate index values are sorted, not rejected, on this path — still send unique 0..N-1.

POST /api/v1/fast-check-stream

frame.index must fall in 0..(frames_required - 1). An index at or above frames_required returns 400. Cover every index from 0 to N-1.

Version pinning

Pin an explicit V3.1.1 alias. Do not send a retired id and do not rely on omitted model in production — always set mixed-30-v3_1_1, mixed-60-v3_1_1, or mixed-120-v3_1_1.

Quick checklist

• Pin mixed-30-v3_1_1, mixed-60-v3_1_1, or mixed-120-v3_1_1.
• Send exactly 30, 60, or 120 consecutive frames to match the alias.
• X-Model-Version: latest with frame_count 30 / 60 / 120 also resolves to V3.1.1.
• Read min_frames from GET /api/v1/models or useModels() before capture.