API REFERENCE

Errors & limits

JSON errors with a stable type to branch on; limits default to 100 requests a minute.

01.The error shape

{
  "error": {
    "type": "unsupported_language",
    "message": "\"xx\" is not one of the 30 supported language codes.",
    "doc_url": "https://thefamiliarlab.com/docs/languages"
  }
}

Branch on type, log message, follow doc_url -- messages may be reworded; types are stable within /v1.

02.Request IDs

HTTP/1.1 200 OK
Familiar-Request-Id: req_7hk2p0d4

Every response carries a Familiar-Request-Id header; log it and include it when reporting an issue (Help Center).

03.Status codes

TABLE 01 · WHAT EACH CODE MEANS
CODE	TYPE	MEANING
400	`invalid_request`	A field is missing or malformed; the message names it.
401	`invalid_key`	No key, a malformed key, or a rotated-away key.
403	`api_access_disabled`	Valid key, API access disabled for its organization (billing hold or abuse review).
404	`not_found`	No such resource under your organization.
409	`conflict`	Wrong state, e.g. rendering a `manual` dub not `in_review`, or deleting one mid-render.
422	`unsupported_language`	Target outside the 30 output languages, source outside the 99, or source equal to a target.
422	`validation_failed`	Well-formed fields that can't be honored together; the message names the pair.
429	`rate_limited`	Too many requests; back off per Retry-After.
5xx	`internal`	Our side. Safe to retry with backoff.

04.Example bodies

409 · RENDER OUT OF STATE

{
  "error": {
    "type": "conflict",
    "message": "dub_31xk9m is \"rendering\"; /render is only valid at \"in_review\".",
    "doc_url": "https://thefamiliarlab.com/docs/dubbing/transcript"
  }
}

429 · RATE LIMITED

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "type": "rate_limited",
    "message": "Request rate above your organization's limit; retry after 12 seconds.",
    "doc_url": "https://thefamiliarlab.com/docs/errors"
  }
}

05.Rate limits

The default limit is 100 requests per minute per organization. Every response reports where you stand:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1786731720

Past it, requests return 429 with Retry-After in seconds; honor it and the limiter recovers immediately. Jobs already accepted are never dropped by the limiter.

06.Default limits

TABLE 02 · DEFAULTS PER ORGANIZATION
LIMIT	DEFAULT
API request rate	100 requests per minute
Concurrent dub renders	10
Concurrent live sessions (experimental)	2 (once live is enabled)
Upload size	10 GB per file
Source duration	24 hours per video
Resolution	up to 4K, matching the source
Audio layout	true 5.1 surround or stereo, chosen per job
Target languages	29 per dub -- the full set minus the source
Page size (`limit`)	20 default · 100 max
`Idempotency-Key` window	24 hours
Webhook delivery	10-second acknowledgement · retried up to 24 hours

Every default is raised the same way: ask your point of contact.

07.Idempotent retries

Send an Idempotency-Key header (any unique string, e.g. a UUID) on any POST and retries with the same key return the original result instead of creating a second resource. Keys are remembered for 24 hours; reusing one with a different body returns 409.

curl -X POST https://api.thefamiliarlab.com/v1/dubs \
  -H "Authorization: Bearer $FAMILIAR_API_KEY" \
  -H "Idempotency-Key: 4c1b2f0e-9d3a-4d8e-b1c7-2f6a0e8d5b91" \
  -F "source_url=https://cdn.yourapp.com/upload.mp4" \
  -F "target_langs=es"

Webhooks can also arrive twice -- dedupe on the event id; see Webhooks.

08.Access

The API is enterprise-only: private access under a Studio contract, with volume pricing, raised limits, ProRes masters on request, and a named point of contact. Book a call and your key is issued with the contract.

Book a call →See the benchmarks