Docs
Log inStart free
API referenceVideo analyses

Get a video analysis

The state of a video analysis: queued / processing (poll again), ready (result) or failed (error).

?words=true adds the word-level transcript. ?t0=&t1= (seconds) cuts the result to one stretch — shots, words, sound segments, sfx and music marks inside it. result.motion says what moves inside shots (events/min, static share, blank runs, recommended_probes); its events page by t0/t1. ?detail=events|strips (with t0/t1, optional fps) re-senses the window: exact motion events, or labelled dense frames (window at most 30 s). Free; CPU, seconds.

GET
/video-analyses/{analysisId}

Authorization

bearerAuth
AuthorizationBearer <token>

Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….

In: header

Path Parameters

analysisId*string
Formatuuid

Query Parameters

words?string
Value in"true" | "false"
t0?|

Window start, seconds.

Range0 <= value
t1?|

Window end, seconds.

Range0 <= value
detail?string

With t0/t1: re-sense the window — exact motion events, or labelled dense contact sheets (window <= 30 s).

Value in"events" | "strips"
fps?number

Sensing fps for detail=events (default 15), frame rate for detail=strips (default 8).

Range0.5 <= value <= 30

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/video-analyses/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "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"
  }
}

Analyse a reference video POST

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

Find the best clips in an analysed video GET

The best self-contained reels in an analysed video, ranked 0-100, each with snapped cut points (start on a sentence start with a short head; end on a sentence end with a 0.45 s tail past the last word