HTTP API

One endpoint, buffered JSON or streaming NDJSON.

POST /api/analyze runs the same analyzer behind the browser. Send Accept: application/x-ndjson for live progress, or use a normal JSON response for headless agents.

Open API contract

Discover the contract

GET /api/analyze returns a machine-readable contract for the endpoint.

curl -s http://localhost:3000/api/analyze

Buffered JSON

Use this mode when you just need the final result object.

curl -s -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/VIDEO_ID"}'

Streaming NDJSON

Use this mode for live progress. The stream emits progress objects, then one final result object. Errors arrive as an error object on the stream.

curl -N -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"url":"https://youtu.be/VIDEO_ID"}'

Request fields

All optional fields have defaults that match the web app.

url: Required YouTube URL.
topK: Integer from 1 to 24. Default: 8.
mode: density or top-k. Default: density.
candidateIntervalSeconds: Seconds between sampled frames. Default: 8.
maxCandidateFrames: Candidate frames sent to vision. Default: 36.
frameWidth: Extracted frame width in pixels. Default: 768.