media

Get authoring context for a media item (faces + transcript + beat/word grids)

The read-only context an agent needs to author a composition over this source: the detected face/subject roster (face-0 = primary speaker, with normalized bbox + active-speaker share), the transcript, the temporal grids — beatGrid (a MUSIC bed's rhythm: bpm, beatTimesMs in milliseconds, confidence, method) and wordGrid (VO word-onset timings in milliseconds, from the transcript) — and a presigned thumbnail (~the footage at a glance). For stills at CHOSEN timestamps, call preview_frame with a one-clip composition over this media. Call this before authoring crop intents (reframe) and overlay/caption timing. The transcript and wordGrid cover one utterance page (default 20); pass transcript.data.pagination.nextCursor as after for later words. Faces are lazily detected — faces.status is not_detected until a compose/detect pass has run over the source, never a faked empty roster. beatGrid is null until beat analysis has run: generated music beds are analyzed automatically at delivery; an uploaded/imported bed may not carry a grid yet (on-demand analysis is not client-triggerable today). audioRole is the DECLARED role of an audio asset (vo | music | sfx | ambience) — author the clip source's audioRole from it; envelope carries the coarse envelopeClass (transient | sweep | ambient) plus any probed attack/centroid/volume stats. Both are null for footage/images or an undeclared audio asset.

get/v1/media/{id}/context

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/media/{id}/context
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.cueframe.ai/api/auth/mcp/authorize, token URL https://api.cueframe.ai/api/auth/mcp/token, scopes: media:read)
    • API key in header PAYMENT-SIGNATURE

Path parameters

idstring required

Query parameters

limitinteger

Transcript utterances per context page (default 20, maximum 100).

afterstring

Zero-based utterance cursor from transcript.data.pagination.nextCursor.

Response

Authoring context.

mediaIdstring required
durationSecnumber nullable required
widthnumber nullable required
heightnumber nullable required
audioRole'vo' | 'music' | 'sfx' | 'ambience' nullable required

DECLARED audio role of this asset (audio-substrate P0): 'vo' (narration), 'music' (bed that ducks under speech), 'sfx' (one-shot hit), 'ambience' (a bed that HOLDS under VO — never ducks). Author the clip source's audioRole from this. Null for footage/images or an undeclared audio asset.

Changes

No recorded changes to this operation across all 1 revision of this API.