--- title: "Request Video Moments Api" method: POST path: "/v2/videos/{video_id}/moments/request" tags: ["Video Emotion API"] --- # Request Video Moments Api `POST /v2/videos/{video_id}/moments/request` ## Request - Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.imentiv.ai/v2/videos/{video_id}/moments/request` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer - OAuth 2 - Authorization code: `https://api.imentiv.ai/oauth/authorize` - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.write` Request Moments for a processed video. Credits are charged once per video. Moments are not computed for a video until they are requested here. The video must be completed (`409` otherwise). A successful request charges the credits once, queues the computation and returns the same body as `GET /v2/videos/{video_id}/moments` (`status: computing`, then `ready` as that call is polled). Requesting is idempotent: when Moments was already requested for the video, this returns `200` with the current moments and charges nothing. Moments stay with the video through edits, trimming and reprocessing; recomputing them after such changes is free. With too few credits the call answers `402` and nothing is requested. Credits are charged once per video, whatever the number of attempts. If a call fails with a server error after the charge, repeat it: it completes the request and charges nothing more. A second request for the same video made while the first is still being processed answers `409`; retry it. Requires the same access as the video's other charged analyses (the owner or a member allowed to write) and, for a delegated app, the `media.write` scope. ## Path parameters - `video_id` string, required: The unique video ID of the video to request moments for ## Response `200` Successful Response - VideoMomentsResponse: Moments for a video. `status` is `ready` (moments below), `computing` (first computation in progress; poll again), `failed` (the last computation failed for the current inputs) or `unavailable` (the video has not finished processing, or Moments was not requested for it). `stale` is true when the video changed since the moments were computed; the previous moments are returned while they are recomputed. - `video_id` string, required - `status` string, required: `ready`, `computing`, `failed` or `unavailable`. - `reason` string, nullable: Why `status` is `unavailable` when the video is complete: `not_requested` means Moments has not been requested for this video (see `POST /v2/videos/{video_id}/moments/request`). Null otherwise, including while the video is still processing. - `stale` boolean: True when a recomputation is pending for newer inputs. - `generation` integer, nullable: Which computation these moments belong to. Null when no moments are returned. Compare it together with `profile_version` and `computed_at`; it does not change on every recomputation. - `profile_version` string, nullable: Analysis profile version these moments were computed with, the same value as `profile.version` when a profile is present. Null when no moments are returned. - `moments` Moment[] - `id` string, required: Id of this moment. A later computation may assign a new id. `GET /v2/videos/{video_id}/moments/resolve` follows an id from an earlier computation to the current one, or reports that it is gone or unknown. Ids from older computations may be reported as unknown. - `kind` string, required: What happened, for example `eye_closure.microsleep` or `sentiment_flip`. - `subject` string, required: The subject it belongs to; join with `subjects[].id`. - `subject_resolution` string, required: How the subject was identified: `face`, `speaker` or `person`. - `baseline_source` string, nullable: Which baseline the deviation was measured against, when one was used. - `start_ms` integer, required - `end_ms` integer, required - `duration_ms` integer, required: Observed duration, in milliseconds. - `resolution_ms` integer, required - `modalities` MomentSpan[] - `modality` string, required: `face`, `voice` or `words`. - `start_ms` integer, required: Start, in milliseconds of video time. - `end_ms` integer, required: End, in milliseconds of video time. - `resolution_ms` integer, required: Time resolution of this modality, in milliseconds. - `anchor` MomentAnchor: What a moment responds to: a transcript sentence or a stimulus. - `kind` string, required: `sentence` or `stimulus`. - `id` string, required: The sentence or stimulus id. - `start_ms` integer, required - `end_ms` integer, required - `confidence` number, nullable: 0-1, when calibrated. - `score` number, required: Relative importance used to rank moments. - `evidence` object: Kind-specific measurements. `contaminated` is `true` when some of the voice or words evidence overlapped known non-human audio; it is absent otherwise. - `evidence_quality` string[]: Which evidence overlapped known non-human audio, such as a voice assistant or music: `audio_overlap:voice` and/or `audio_overlap:words`, in that order. Empty when none did, and on moments computed before this field existed. - `source_events` string[]: Ids of the signal events it was built from. - `coverage` MomentCoverage[] - `subject` string, required - `kind` string, required - `status` string, required: `measured`, `partial` or `unavailable`. - `reason` string, nullable: Why coverage is partial or unavailable. - `observed_s` number: Seconds in which the kind could be observed. - `detail` string, nullable - `detected_count` integer, nullable: Set when not every detected moment of this kind is listed (reason `cap_reached`): how many were detected for this subject. - `retained_count` integer, nullable: Set together with `detected_count`: how many of those moments are listed in `moments`. - `stimulus_coverage` StimulusCoverage[] - `subject` string, required - `stimulus_id` string, required - `status` string, required - `reason` string, nullable - `observed_s` number: Seconds of the stimulus's response window in which the subject could be observed. For a subject listed in `visibility`, this can instead be the seconds of that window in which its face was visible. - `counts` object: Number of moments per kind. - `visibility` SubjectVisibility[], nullable: When each face was visible, one entry per subject. A subject not listed has unknown visibility. Null when visibility is not included with these moments. - `subject` string, required: The subject; join with `subjects[].id`. - `visible_spans` VisibleSpan[]: When the face was visible, in order and never overlapping. Time outside every span is time the face was not visible. Empty when the face was never visible. - `start_ms` integer, required: Start, in milliseconds of video time (inclusive). - `end_ms` integer, required: End, in milliseconds of video time (exclusive). - `visible_ms` integer, required: Total visible time, in milliseconds: the sum of `visible_spans`. - `uninterrupted` boolean, required: True when each span is continuous visibility. False when brief absences inside a span were joined over, so a span alone does not prove the face was visible throughout it. - `profile` MomentsProfile: The analysis profile the moments were computed with. - `id` string, nullable: For example `conversation`, `sales` or `in_vehicle`. - `version` string, nullable - `schema_version` string, nullable: Version of the moments result format. - `safety_kinds` string[], nullable: Kinds of moment this profile treats as safety-relevant and ranks ahead of the others; empty when it has none. Null for moments computed before this was reported. - `subjects` MomentSubject[] - `id` string, required: `face:{face_id}` or `speaker:{speaker_id}`. - `face_id` string, nullable - `speaker_id` string, nullable - `person_id` string, nullable: The linked project person, if any. - `is_driver` boolean, nullable: Set on in-vehicle videos for the driver. - `role` string, nullable: The speaker's role, for example `agent` or `customer`. - `computed_at` string, date-time, nullable: When these moments were computed. ## Other responses - `401`: Missing, malformed or rejected credentials — no `X-API-Key` / `Authorization: Bearer `, an expired token, or a caller that lacks the role the route requires. Note that this API answers *authorization* failures with 401 as well as 403 (see the 403 entry where a route declares both). - `402`: Not enough credits, or a workspace budget refuses the charge. Nothing was charged and Moments was not requested. - `404`: No such resource, or it is not visible to this caller. Ownership failures are reported as 404 rather than 403 so the API does not confirm the existence of another account's records. - `409`: Either the video has not finished processing, and the body is what `GET /v2/videos/{video_id}/moments` returns for it (`status: unavailable`); or a request for the same video is already being processed, and the body is `{"detail": ...}`: retry it. - `422`: Validation Error - `503`: The credits or budgets that would pay for the request could not be checked. Nothing was charged; retry. ## Changes - **2026-10-31** `bd825cd86e8c`: 1 info - endpoint added [Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/moments/request/post.md) --- [API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/9c4d258def38?raw)