{"service":"yt2ctx","endpoint":"/api/analyze","method":"POST","summary":"Analyze a YouTube video into a VLM-ready context pack: timed transcript, representative frames, and cinematic grammar artifacts.","request":{"contentType":"application/json","body":{"url":"string (required) — youtube.com/watch, youtu.be, or /shorts URL","topK":"integer 1–24 (default 8) — number of frames to select","mode":"'density' | 'top-k' (default 'density') — frame selection strategy","extractionKind":"'text' | 'full' (default 'full') — text-only transcript or full visual context pack","candidateIntervalSeconds":"number 1–120 (default 8) — seconds between sampled frames","maxCandidateFrames":"integer 4–80 (default 36) — candidate frames sent to vision","frameWidth":"integer 256–1600 (default 768) — extracted frame width in pixels"}},"responseModes":{"streaming":"Send `Accept: application/x-ndjson`. Returns newline-delimited JSON: zero or more {type:'progress',stage,label,pct,...} events, then one {type:'result',result:{...}} line. Failures arrive as a {type:'error',message} line.","buffered":"Send any other Accept value. Returns a single JSON result object, or {error} with HTTP 400 on failure."},"result":{"id":"string — job identifier","metadata":"{ title, uploader, durationSeconds }","markdown":"string — the watch pack","frames":"Array<{ fileName, timestamp, score, description, labels, imageUrl, imageDownloadUrl }>","cinematic":"{ styleMarkdown, shotSpecMarkdown, promptMarkdown, shotSpecs, slopWarnings }","zipUrl":"string — Blob URL of the full artifact ZIP","zipDownloadUrl":"string — Blob download URL of the full artifact ZIP"},"examples":{"buffered":"curl -s -X POST /api/analyze -H 'Content-Type: application/json' -d '{\"url\":\"https://youtu.be/VIDEO_ID\"}'","streaming":"curl -N -X POST /api/analyze -H 'Content-Type: application/json' -H 'Accept: application/x-ndjson' -d '{\"url\":\"https://youtu.be/VIDEO_ID\"}'"},"notes":["Requires OPENAI_API_KEY configured on the server.","Guest users can run 10 free text-only extractions. Full context extractions require an authenticated web session.","Completed authenticated analyses are saved to the signed-in user's Postgres video library.","maxDuration is 300s; long videos are better processed via the CLI or MCP server.","Only analyze videos you have the right to download."]}