Agent quickstart

The brief

Base https://api.framequery.com/v1/api. Header Authorization: Bearer $FRAMEQUERY_API_KEY (keys start fq_live_, server-side only). Success {"data": …}; error {"error", "code", "docUrl", "param"}: branch on code.

1. Create. POST /jobs/from-url, header Idempotency-Key: <uuid>, body {"url": "https://…/a.mp4", "processingMode": "all"} (all | transcript | vision) → data.jobId.

   Local file: POST /jobs {"fileName": "a.mp4", "fileSizeBytes": 1048576}, then, within an hour, PUT the bytes to data.uploadUrl sending every data.uploadHeaders entry and no Authorization. The URL accepts exactly one object (a 412 means it already landed; read the job rather than re-uploading).

2. Wait. GET /jobs/{jobId}?include=none every 5–15 s until data.state is completed, failed, cancelled or expired (ignore status). Or pass "callbackUrl" at create for a signed webhook.
3. Read. GET /jobs/{jobId}/transcript → data.text, data.speakers[], data.segments[{startTime, endTime, text, speaker}]; ?format=srt|vtt|txt for a file. GET /jobs/{jobId}/scenes → data.scenes[{index, startTime, endTime, description, objects[], colorPalette[], shotType, shotAngle}]. Times in seconds.

Errors. Retry 429, 503 and 409 IDEMPOTENCY_IN_PROGRESS after Retry-After; retry 500 with exponential backoff. Reuse the same Idempotency-Key on every retry. 409 RESULTS_NOT_READY: later. 404 RESULTS_UNAVAILABLE: never (see reason). 402: out of credits. Others: fix the request. state failed → data.error {code, message, stage}; completed stages stay readable.

Copy-paste script

The brief above as a runnable bash script (needs curl and jq):

set -euo pipefail
API=https://api.framequery.com/v1/api
AUTH="Authorization: Bearer $FRAMEQUERY_API_KEY"

JOB_ID=$(curl -sS -X POST "$API/jobs/from-url" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "https://example.com/interview.mp4", "processingMode": "all"}' | jq -r .data.jobId)

while :; do
  STATE=$(curl -sS "$API/jobs/$JOB_ID?include=none" -H "$AUTH" | jq -r .data.state)
  echo "state: $STATE"
  case "$STATE" in completed|failed|cancelled|expired) break ;; esac
  sleep 10
done

curl -sS "$API/jobs/$JOB_ID/transcript" -H "$AUTH" | jq '.data.segments[:3]'
curl -sS "$API/jobs/$JOB_ID/scenes" -H "$AUTH" | jq '.data.scenes[:3]'

With an SDK

The Python and TypeScript SDKs do the create, upload, wait and fetch in one call, with idempotency keys and retries built in:

from framequery import FrameQuery

fq = FrameQuery()  # reads FRAMEQUERY_API_KEY
result = fq.process("https://example.com/interview.mp4")  # or a local path
print(result.transcript.text if result.transcript else "no transcript")
for scene in result.scenes or []:
    print(scene.start_time, scene.description)

Rules of thumb

• Decide everything from state and stages.*.status. The status string is a legacy internal value and changes without notice.
• Poll no faster than every 5 seconds; estimatedCompletionTimeSeconds on the job is a good hint. GET requests are limited to 600 per minute per account.
• Send an Idempotency-Key on every create and reuse it on retries. A replay returns the original job with Idempotent-Replayed: true.
• A failed or skipped stage costs nothing. A job whose vision stage failed can still have a completed, readable (and charged) transcript.
• Never ship the key to a browser or mobile app. Proxy through your server.
• Cost per footage-hour: $1.50 all, $1.15 vision, $0.35 transcript (per audio track); camera RAW $2.50 / $1.65 / $0.85. Per second, 30 s minimum per job. Check before spending with GET /pricing/estimate?durationSeconds=600&mode=all (no key) and GET /quota (data.api.availableCents).
• More detail: Jobs, Job lifecycle, Results, Errors, OpenAPI.