Skip to main content

Get Video Moments Api

GET 
/v2/videos/{video_id}/moments

Notable moments in a processed video, per face or speaker.

Same authorization as other video GETs (owner, admin, shared, or sample).

Moments are computed asynchronously once the video, its audio and its transcript have finished processing, and again after edits that change them (face merges, speaker links, linked people, reprocessing). This call never waits for that:

  • status: ready returns the moments. With stale: true the video changed since they were computed; these are the previous moments and a recomputation is queued.
  • status: computing means the first computation is queued or running. Poll again.
  • status: failed means the last computation failed for the video as it is now.
  • status: unavailable means the video has not finished processing, or Moments has not been requested for it. In the second case reason is not_requested; request it with POST /v2/videos/{video_id}/moments/request. Moments already computed for a video are still returned here, but the AI insights conversation does not use them until Moments has been requested for the video.

coverage says, per subject and kind, whether that kind of moment could be looked for. No moments of a kind means none happened only where its coverage is measured. Join moments[].subject to subjects[].id for the face, speaker and linked person. New kinds and coverage reasons may appear at any time; treat unknown values as opaque.

generation and profile_version say which computation these moments belong to. Compare them together with computed_at: a recomputation can leave generation and profile_version unchanged while computed_at moves. profile_version is the same value as profile.version when a profile is present.

visibility says when each face was on screen, as half-open spans of video time; time outside every span is time the face was not visible. uninterrupted: false means brief absences inside a span were joined over. A reaction whose response window includes time the face was not visible carries evidence.partly_seen: true. visibility is null when it is not included with these moments: an older video or result, no usable visibility data, or left out to keep the result within its size limit. Null never means fully seen, and a subject missing from it has unknown visibility.

Request​

Responses​

Successful Response