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. 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.
API key auth. Prefix cf_live_ for production orgs, cf_test_ for sandbox.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/media/string/context"{ "mediaId": "string", "durationSec": 0, "width": 0, "height": 0, "thumbnail": { "url": "string" }, "faces": { "status": "ready", "windows": [ { "window": { "startSec": 0, "endSec": 0 }, "faces": [ { "faceId": "string", "bbox": { "x": 0, "y": 0, "width": 0, "height": 0 }, "speakingShare": 0 } ] } ] }, "transcript": { "status": "ready", "data": { "mediaItemId": "string", "language": "string", "model": "string", "fullText": "string", "utterances": [ { "property1": null, "property2": null } ], "data": [ { "property1": null, "property2": null } ], "pagination": { "hasMore": true, "nextCursor": "string", "prevCursor": "string" } } }, "beatGrid": { "bpm": 0, "beatTimesMs": [ 0 ], "confidence": 0, "method": "requested-anchored" }, "wordGrid": { "wordTimesMs": [ 0 ] }, "audioRole": "vo", "envelope": { "envelopeClass": "transient", "attackMs": 0, "spectralCentroidHz": 0, "meanVolumeDb": 0, "maxVolumeDb": 0 }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "x402Version": 2, "accepts": [ {} ], "error": "string"}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null } }}