API referenceVideo analyses
Analyse a reference video
Break any video into what an agent can read, in one call: frame-accurate shots (ffmpeg scene cuts, adaptive dark-scene cuts and dips to black) with duration, motion energy, a 480p keyframe, a class (t
alking head, B-roll, screen recording, motion graphics, title card…), on-screen text, graphics and voice-over; contact sheets of up to 16 shots with the shot number and time range burned in; the transcript; the sound (speech / music / singing segments, timed sound effects, and the music reading only when there is music); and condensed, the whole video as one readable timeline. The first 10 minutes are analysed. Asynchronous — 202 with an analysis at queued; poll GET /video-analyses/{analysisId}. 200 when the same source + options already has an analysis (returned instead of a new job). Free.
Authorization
bearerAuth AuthorizationBearer <token>
Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/video-analyses" \ -H "Content-Type: application/json" \ -d '{}'{
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "queued",
"source": {
"kind": "url",
"url": "string",
"media_asset_id": "f83c59c2-d228-4515-88d6-11fa95820958"
},
"options": {
"maxShots": 0,
"sheetCols": 0,
"threshold": 0,
"transcribe": true,
"summarize": true,
"sound": true,
"classify": true,
"blueprint": true,
"blueprintModel": "flash"
},
"error": "string",
"cached": true,
"created_at": "string",
"completed_at": "string",
"result": {
"analyzer": "string",
"source": {
"url": "string",
"sha256": "string",
"duration_sec": 0,
"analyzed_sec": 0,
"truncated": true,
"width": 0,
"height": 0,
"fps": 0,
"has_audio": true
},
"stats": {
"shot_count": 0,
"cuts_per_min": 0,
"mean_shot_sec": 0,
"median_shot_sec": 0,
"mean_motion_energy": 0
},
"shots": [
{
"i": 0,
"start": 0,
"end": 0,
"duration": 0,
"motion_energy": 0,
"cut_score": 0,
"cut": "start",
"black": true,
"keyframe_url": "string",
"text": "string",
"kind": "talking_head",
"framing": "wide",
"on_screen_text": "string",
"graphics": true,
"voice_over": true
}
],
"contact_sheets": [
{
"url": "string",
"first_shot": 0,
"last_shot": 0,
"cols": 0
}
],
"transcript": {
"text": "string",
"language": "string",
"provider": "string",
"words": [
{
"w": "string",
"s": 0,
"e": 0
}
]
},
"audio": {
"features_url": "string",
"bpm": 0,
"beats_per_bar": 0,
"grid_confidence": 0,
"downbeat_offset_sec": 0,
"beats": [
0
],
"energy": {
"fps": 0,
"values": [
0
]
},
"onsets": [
0
]
},
"sound": {
"features_url": "string",
"analyzer": "string",
"detect": {
"property1": null,
"property2": null
},
"segments": [
{
"t": 0,
"d": 0,
"kind": "speech"
}
],
"sfx": [
{
"t": 0,
"d": 0,
"tag": "string",
"s": 0
}
],
"music": {
"property1": null,
"property2": null
}
},
"condensed": "string",
"window": {
"t0": 0,
"t1": 0
},
"summary": "string",
"blueprint": {
"property1": null,
"property2": null
},
"notes": [
"string"
],
"cost": {
"stt_seconds": 0,
"summary_usd": 0,
"classify_usd": 0,
"blueprint_usd": 0
},
"timings_ms": {
"property1": 0,
"property2": 0
}
},
"reused": true,
"note": "string"
}
}{
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "queued",
"source": {
"kind": "url",
"url": "string",
"media_asset_id": "f83c59c2-d228-4515-88d6-11fa95820958"
},
"options": {
"maxShots": 0,
"sheetCols": 0,
"threshold": 0,
"transcribe": true,
"summarize": true,
"sound": true,
"classify": true,
"blueprint": true,
"blueprintModel": "flash"
},
"error": "string",
"cached": true,
"created_at": "string",
"completed_at": "string",
"result": {
"analyzer": "string",
"source": {
"url": "string",
"sha256": "string",
"duration_sec": 0,
"analyzed_sec": 0,
"truncated": true,
"width": 0,
"height": 0,
"fps": 0,
"has_audio": true
},
"stats": {
"shot_count": 0,
"cuts_per_min": 0,
"mean_shot_sec": 0,
"median_shot_sec": 0,
"mean_motion_energy": 0
},
"shots": [
{
"i": 0,
"start": 0,
"end": 0,
"duration": 0,
"motion_energy": 0,
"cut_score": 0,
"cut": "start",
"black": true,
"keyframe_url": "string",
"text": "string",
"kind": "talking_head",
"framing": "wide",
"on_screen_text": "string",
"graphics": true,
"voice_over": true
}
],
"contact_sheets": [
{
"url": "string",
"first_shot": 0,
"last_shot": 0,
"cols": 0
}
],
"transcript": {
"text": "string",
"language": "string",
"provider": "string",
"words": [
{
"w": "string",
"s": 0,
"e": 0
}
]
},
"audio": {
"features_url": "string",
"bpm": 0,
"beats_per_bar": 0,
"grid_confidence": 0,
"downbeat_offset_sec": 0,
"beats": [
0
],
"energy": {
"fps": 0,
"values": [
0
]
},
"onsets": [
0
]
},
"sound": {
"features_url": "string",
"analyzer": "string",
"detect": {
"property1": null,
"property2": null
},
"segments": [
{
"t": 0,
"d": 0,
"kind": "speech"
}
],
"sfx": [
{
"t": 0,
"d": 0,
"tag": "string",
"s": 0
}
],
"music": {
"property1": null,
"property2": null
}
},
"condensed": "string",
"window": {
"t0": 0,
"t1": 0
},
"summary": "string",
"blueprint": {
"property1": null,
"property2": null
},
"notes": [
"string"
],
"cost": {
"stt_seconds": 0,
"summary_usd": 0,
"classify_usd": 0,
"blueprint_usd": 0
},
"timings_ms": {
"property1": 0,
"property2": 0
}
},
"reused": true,
"note": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}