Clip Suggestions

Fetch AI-scored highlight windows for a recording.

AI-scored highlight windows for a recording — the raw material for renders. Some suggestions are carousel-kind: they propose an angle over the whole recording and carry no clip window (start_ms/end_ms are null).

Tier: platform. Base URL https://app.castmagic.io.

List clip suggestions

GET https://app.castmagic.io/v1/recordings/:id/clip-suggestions

Pass generate=true to queue suggestion generation when none exist yet. Generation is asynchronous, so poll again after a minute or two.

Query Parameters

Name	Type	Description
generate	Boolean	true to queue generation when no suggestions exist

200: OK

{
    "recording_id": "e1...",
    "suggestions": [
        {
            "id": "cs1...",
            "title": "The pricing objection moment",
            "excerpt": "...here's the thing about pricing...",
            "kind": "clip",
            "start_ms": 154000,
            "end_ms": 178000,
            "created_at": "2026-08-21T22:10:00Z"
        }
    ],
    "count": 1,
    "generating": false
}

200: OK generation queued

{
    "recording_id": "e1...",
    "suggestions": [],
    "count": 0,
    "generating": true
}