API REFERENCE
Authentication
One key per organization, issued under a Studio contract. Every request carries it in the Authorization header.
01.The header
curl https://api.thefamiliarlab.com/v1/usage \ -H "Authorization: Bearer $FAMILIAR_API_KEY"
Keys look like fam_sk_… and belong to your organization, not to an individual user. A request without a valid key returns 401; a valid key on a plan without API access returns 403 -- see Errors & limits.
02.Acting for a creator
Platforms integrate once and act on behalf of many creators. Create a creator profile per user (Creator profiles) and pass its creator_id on dubs, live sessions, and Do Not Translate writes -- that is what scopes their preferences to them.
| RESOURCE | SCOPE |
|---|---|
| Dubs, live sessions, outputs | Your organization's own jobs only. |
| Creator profiles | Creators your organization created. |
| Do Not Translate + context | Any scope keyed to your creators, streams, or jobs. |
| Usage | Your organization's credit balance and cycle. |
03.Handling keys
- Server-side only. Never ship a key in client code, an app bundle, or a public repo -- anyone holding it can spend your credits.
- Rotation: contact the team and a replacement is issued immediately; the old key dies the moment the new one is confirmed.
- Environment separation: ask for a second key if you want staging and production separated; usage reports per key.
04.Auth errors
| CODE | TYPE | MEANING |
|---|---|---|
| 401 | invalid_key | No Authorization header, a malformed key, or a key that was rotated away. |
| 403 | api_access_disabled | The key is valid but API access is disabled for its organization (billing hold or abuse review). |
{
"error": {
"type": "invalid_key",
"message": "The API key in the Authorization header does not exist.",
"doc_url": "https://thefamiliarlab.com/docs/authentication"
}
}The full error format and every status code live in Errors & limits.
05.Access
The API is enterprise-only: private access under a Studio contract, with volume pricing, raised limits, and a named point of contact for the integration. Book a call and your key is issued with the contract.