SDKs

All SDKs are open source in FrameQuery/framequery-sdks. They follow one design, so method names, field names and error classes match across languages, and they match the API: every field is the JSON name in the language's usual case (jobId is job_id in Python, jobId in TypeScript).

The Go, Rust and Ruby SDKs are at 0.1 and move to the 0.2 surface next; see their READMEs in the SDK repository. This page documents 0.2.

What the SDKs do for you

• Uploads straight to storage, streamed from disk and never read into memory whole: one PUT up to 32 MiB, resumable 16 MiB chunks above that, resumed automatically after network errors.
• Waiting on state with sensible backoff; wait() returns the terminal job and never raises for failed.
• Retries on 429, 503 and connection errors, honouring Retry-After, with an idempotency key on every create so a retry never creates a second job.
• Typed errors carrying code, doc_url / docUrl, param, request_id / requestId and retry_after / retryAfter.
• Webhook verification without extra dependencies.

Client

from framequery import FrameQuery, AsyncFrameQuery

fq = FrameQuery()                       # api_key defaults to FRAMEQUERY_API_KEY
fq = FrameQuery(api_key="fq_live_...", timeout=60, max_retries=3)

async with AsyncFrameQuery() as afq:    # same methods, as coroutines
    job = await afq.jobs.get(job_id)

Keyless calls (pricing.get, pricing.estimate, formats.list) and webhook verification work without a key.

Process in one call

process() creates the job (upload or URL), waits for it, and fetches whichever results completed.

result = fq.process("interview.mp4", processing_mode="all", metadata={"assetId": "A003_C008"})
result.job            # Job (state "completed")
result.transcript     # Transcript, or None if that stage was skipped
result.scenes         # list[Scene], or None if that stage was skipped

If the job ends failed or expired, process() raises JobFailedError (with job, code and stage); cancelled raises JobCancelledError. Stages that completed are still readable through fq.jobs.transcript(...) and fq.jobs.scenes(...).

Methods

jobs.get sends include=none by default; results come from transcript() and scenes().

Errors

All API errors derive from APIError, and everything from FrameQueryError.

from framequery import InsufficientCreditsError, RateLimitError, ResultsNotReadyError

try:
    transcript = fq.jobs.transcript(job_id)
except ResultsNotReadyError as err:
    print("not yet, retry in", err.retry_after, "s")
except InsufficientCreditsError as err:
    print("top up:", err.doc_url)

Webhooks

See Webhooks for complete handlers. The secret defaults to FRAMEQUERY_WEBHOOK_SECRET. In Python, framequery.webhooks.verify(payload, headers, secret) and framequery.webhooks.unwrap(...) also work without a client. Always pass the raw request body.

Other languages and plain HTTP

Any HTTP client works: see the API reference for every endpoint, or generate a client from the OpenAPI document.