---
title: "Get authoring context for a media item (faces + transcript + beat/word grids)"
method: GET
path: "/v1/media/{id}/context"
tags: ["media"]
---

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

`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`

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.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `after` string

## Response `200`

Authoring context.

- MediaContextResponse: Read-only authoring context for a source media item: detected face roster + transcript + the temporal grids (beat / word) an agent cuts to, the DECLARED audioRole + envelope of an audio asset, and the paid-enhancement block (facts already computed + offers for what is missing).
  - `mediaId` string, required
  - `durationSec` number, nullable, required
  - `width` number, nullable, required
  - `height` number, nullable, required
  - `thumbnail` object, nullable, required: Presigned processing thumbnail (~1 week) — the footage at a glance. For stills at chosen timestamps, use preview_frame with a one-clip composition over this media.
    - `url` string, required
  - `faces` object, required
    - `status` 'ready' | 'not_detected', required
    - `windows` ContextSubjectWindow[], required
      - `detectorVersion` string, required: Version of the face detector that produced this source-window roster.
      - `window` object, required
        - `startSec` number, required
        - `endSec` number, required
      - `faces` ContextFace[], required
        - `faceId` string, required
        - `bbox` object, required
          - `x` number, required
          - `y` number, required
          - `width` number, required
          - `height` number, required
        - `speakingShare` number
  - `transcript` object, required
    - `status` 'ready' | 'not_transcribed' | 'unavailable', required
    - `data` TranscriptResponse, required: Transcript response.
      - `mediaItemId` string, required
      - `language` string, nullable, required
      - `fullText` string, required
      - `utterances` object[], required
      - `data` object[]
      - `pagination` PaginationMeta: Cursor pagination metadata.
        - `hasMore` boolean, required
        - `nextCursor` string, nullable, required
        - `prevCursor` string, nullable, required
  - `beatGrid` object, nullable, required: The MUSIC-role rhythm grid (audio-substrate MVP). Present only for a music bed that carries a computed beat grid; null otherwise. For a music-driven film, cut on these beats (transition midpoints on beats, risers resolving on downbeats).
    - `bpm` number, required
    - `beatTimesMs` number[], required: Beat onset times in MILLISECONDS — divide by 1000 for timeline startTime (composition timeline fields are seconds).
    - `confidence` number, required: Rhythmic-periodicity strength (0–1). Trust the grid for cutting when high; a beatless bed reports low.
    - `method` 'requested-anchored' | 'detected', required: `requested-anchored` = phase-locked to a requested BPM (a generated bed whose prompt named a tempo); `detected` = full beat tracking (import/upload).
  - `wordGrid` object, nullable, required: The VO-role rhythm grid for this bounded transcript page. Present when a transcript exists; null otherwise. Check pagination.hasMore before treating it as a complete voice spine.
    - `wordTimesMs` number[], required: Word onset times in MILLISECONDS for this transcript utterance page — divide by 1000 for timeline startTime (composition timeline fields are seconds).
    - `pagination` PaginationMeta, required: Cursor pagination metadata.
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required
      - `prevCursor` string, 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.
  - `envelope` object, nullable, required: Envelope evidence (audio-substrate P0). `envelopeClass` is always present when an envelope exists (the SFX pack carries it); the numeric probe stats are present only when an audio probe has run. Null when no envelope is stored.
    - `envelopeClass` 'transient' | 'sweep' | 'ambient', required: Coarse temporal shape: 'transient' (a sharp one-shot), 'sweep' (a bounded rise/fall over ~0.5–2s), 'ambient' (an unbounded bed).
    - `attackMs` number
    - `spectralCentroidHz` number
    - `meanVolumeDb` number
    - `maxVolumeDb` number
  - `facts` MediaFact[], required: Derived facts about this source (subject tracks, mattes): what has been computed, its status, and what it was billed. Same shape as GET /media/{id}/facts.
    - `factId` string, required: The persisted fact receipt identity. Reuse pending or ready exact-window facts without dispatching new work.
    - `kind` 'transcript' | 'subjectTrack' | 'matte', required
    - `intent` object, required
      - `kind` 'whole' | 'window', required
      - `window` object: The SOURCE window this fact covers, when it is scoped to a clip.
        - `startSec` number, required
        - `endSec` number, required
    - `status` 'pending' | 'ready' | 'failed', required
    - `summary` object
      - `presenceFraction` number: Matte only: fraction of frames carrying a detected subject (0–1). Below 0.6 there is no reliable silhouette — the matte is delivered but cannot carry a behind-subject graphic, and is NOT charged.
      - `faceCount` number
      - `language` string
      - `wordCount` number
      - `durationSec` number
    - `charge` object: What this fact was BILLED, in USD. Absent when it cost nothing: a compose/render side effect (already paid for inside that operation) or an unusable matte.
      - `usd` number, required
    - `error` object
      - `code` string, required
      - `message` string, required
    - `readyAt` number
  - `offers` MediaFactOffer[], required: Enhancements this source does not have yet, with a server quote. Same shape as GET /media/{id}/facts. Mattes are quoted per-window via POST /media/{id}/matte, never here.
    - `kind` 'transcript' | 'subjectTrack' | 'matte', required
    - `quotedUsd` number, required: The server's price for this enhancement, in USD. Meaningful ONLY when `available` is true — an unavailable offer quotes 0 because there is nothing to price yet.
    - `available` boolean, required
    - `reason` string: Why this cannot be bought right now. Present iff `available` is false. e.g. `media_not_ready` (the source has no known duration yet).

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)