FrameQuery API

The FrameQuery API runs the same server pipeline as the FrameQuery desktop app, behind a REST API. A job has up to two billable stages:

• Vision: scene detection, plus a one-sentence caption for every scene with object labels, a colour palette, shot type and shot angle.
• Transcript: speech-to-text with speaker labels (diarisation), as JSON or as an SRT, WebVTT or plain-text file.

It accepts anything FFmpeg can decode, audio-only files (transcript only), and camera RAW (RED R3D, Blackmagic BRAW, ARRIRAW) for the formats GET /formats reports as enabled. You create a job, upload the file or give us a URL, and read the results once the job's state is completed, either by polling or from a signed webhook.

What you get back

One scene from GET /jobs/{jobId}/scenes:

{
  "index": 3,
  "startTime": 41.2,
  "endTime": 48.9,
  "description": "A woman pours coffee at a kitchen table while a man reads a newspaper in morning light.",
  "objects": ["woman", "man", "coffee-pot", "mug", "newspaper", "table"],
  "colorPalette": ["#d8c3a5", "#8e6c4a", "#3b3a36", "#e9e4d8"],
  "shotType": "medium",
  "shotAngle": "eye-level"
}

One segment from GET /jobs/{jobId}/transcript:

{ "startTime": 41.6, "endTime": 44.1, "text": "Did you see the forecast for tomorrow?", "speaker": "Speaker 2" }

Times are seconds (float) from the start of the media. Every JSON key is camelCase. Full shapes: Results.

Price

$1.50 per footage-hour for vision plus transcript on standard formats: $1.15 for vision only, $0.35 for transcript only. Camera RAW costs $2.50 per footage-hour. Billing is per second with a 30-second minimum per job, and a stage that fails or is skipped is never charged. Above 500 footage-hours in a UTC calendar month the volume rates apply to the extra hours. You prepay with credit packs of $10, $50 or $100; enterprise accounts can pay as they go. See Pricing and billing.

Start here

• Agent quickstart: a short brief for an LLM agent writing code against the API.
• Quickstart: your first job with curl, Python or TypeScript.
• Authentication and keys: get an fq_live_ key and keep it server-side.
• Jobs and Job lifecycle: creating jobs, uploads, state and stages.
• API reference: every endpoint with a copy-pasteable curl command.

Machine-readable

• OpenAPI 3.1, the contract every page here follows: https://api.framequery.com/v1/api/openapi.json. No key needed.
• Keyless discovery: GET /pricing, GET /pricing/estimate and GET /formats.
• Every docs page is also plain Markdown: append .md to its URL, for example /docs/webhooks.md. The index is /docs.md; /llms.txt lists every page and /llms-full.txt holds them all in one file.

Base URL and conventions

https://api.framequery.com/v1/api

• Authenticate with Authorization: Bearer $FRAMEQUERY_API_KEY (or X-API-Key). Keys start with fq_live_.
• Success responses are {"data": …, "requestId": "…"}. Errors are {"error": "…", "code": "…", "docUrl": "…", "param": "…", "requestId": "…"}; branch on code, never on the message. See Errors.
• Every response carries X-Request-Id. Quote it (or requestId) when you contact support.
• Job creation accepts an Idempotency-Key so retries never create a second job. See Jobs.