API overview

The FaceMode REST API creates and manages streaming sessions (audio in, lip-synced avatar video out), avatars, and API keys. For the real-time audio channel itself, see the WebSocket protocol.

Base URL

https://api.facemode.io/api

All paths in this reference are relative to that base, for example POST https://api.facemode.io/api/sessions.

Authentication

Every request needs a FaceMode API key (fm_ followed by 48 hex characters). Two equivalent header formats are accepted:

x-api-key: fm_your_key_here

Authorization: Bearer fm_your_key_here

Authorization: ApiKey fm_... and Authorization: Api-Key fm_... are also accepted. Create keys on the dashboard or via POST /api/keys. Keys can be revoked (PATCH /api/keys/{id}/revoke) or deleted (DELETE /api/keys/{id}).

Scopes

Each key carries a list of scopes. Requests authenticated with a key that lacks the required scope fail with 403 AUTH_INSUFFICIENT_SCOPE.

Scope	Gates
`sessions:create`	`POST /api/sessions`, `POST /api/sessions/{id}/reconnect`
`sessions:read`	`GET /api/sessions`, `GET /api/sessions/{id}`
`sessions:end`	`POST /api/sessions/{id}/heartbeat`, `POST /api/sessions/{id}/end`, `DELETE /api/sessions/{id}`, `DELETE /api/sessions`
`avatars:read`	`GET /api/avatars`, `GET /api/avatars/{id}`, `GET /api/avatars/{id}/download`
`avatars:write`	`POST /api/avatars`, `PUT /api/avatars/{id}`, `DELETE /api/avatars/{id}`
`keys:read`	`GET /api/keys`, `GET /api/keys/{id}`
`keys:write`	`POST /api/keys`, `PATCH /api/keys/{id}/revoke`
`keys:delete`	`DELETE /api/keys/{id}`
`usage:read`	Usage reporting endpoints
`billing:read` / `billing:write`	Billing endpoints
`credits:read`	Credit balance endpoints (opt-in only)

New keys default to sessions:create, sessions:read, sessions:end, avatars:read, and usage:read. Pass an explicit scopes array at creation to grant more, or fewer.

Error envelope

All non-2xx responses share one shape:

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

Some errors add error.details (for example REQUEST_FIELD_UNKNOWN includes details.fields, the list of rejected fields). Scope failures also include top-level requiredScope and grantedScopes fields.

Common error codes

Code	HTTP	Meaning
`AUTH_UNAUTHORIZED`	401	No usable credential on the request
`AUTH_API_KEY_INVALID`	401	Key does not exist or is revoked
`AUTH_API_KEY_EXPIRED`	401	Key passed its `expiresAt`
`AUTH_INSUFFICIENT_SCOPE`	403	Key lacks the required scope
`SESSION_NOT_FOUND`	404	Session ID unknown or not owned by this account
`SESSION_NOT_ACTIVE`	400	Operation requires an `ACTIVE` session
`SESSION_ALREADY_ENDED`	400	Session is already in terminal state
`AVATAR_NOT_FOUND`	404	Avatar ID unknown or not usable by this account
`AVATAR_DELETE_DEFAULT_FORBIDDEN`	403	Platform default avatars cannot be deleted
`AVATAR_DOWNLOAD_NON_CUSTOM_FORBIDDEN`	403	Only custom avatars can be downloaded
`AVATAR_NO_IMAGE`	404	Avatar has no stored image
`API_KEY_NOT_FOUND`	404	Key ID unknown or not owned by this account
`API_KEY_LIMIT_REACHED`	403	Maximum of 5 API keys per account
`INVALID_SCOPES`	400	`scopes` contains unknown scope names
`INVALID_EXPIRY_DATE`	400	`expiresAt` is not a valid date
`EXPIRY_MUST_BE_FUTURE`	400	`expiresAt` must be in the future
`ROOM_INVALID`	400	`room.type`, `room.url`, and `room.token` are required; type must be `livekit` or `daily`
`ROOM_LEGACY_FIELDS`	400	Legacy fields (`byolr`, `livekitUrl`, `livekitToken`) are not supported - use `room`
`ROOM_TYPE_MISMATCH`	400	Reconnect `room.type` differs from the session’s `egressType`
`WAIT_FOR_INGESTION_REMOVED`	400	`waitForIngestion` is no longer supported
`REQUEST_FIELD_UNKNOWN`	400	Body contains unsupported fields; see `error.details.fields`
`INPUT_PROVIDER_INVALID`	400	`inputProvider` is not a supported provider
`INPUT_PROVIDER_MISMATCH`	400	Reconnect `inputProvider` differs from the session’s stored provider
`INSUFFICIENT_CREDITS`	402	Remaining credit balance is below the minimum needed to start a session
`SESSION_LIMIT_REACHED`	409	Concurrent session limit reached (1 concurrent session during beta; sessions in `ENDING` do not count)
`BILLING_DISABLED`	403	Credit purchases are disabled during the beta
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Generic server failure

5xx responses always use curated codes such as SESSION_CREATE_FAILED or API_KEY_FETCH_FAILED, or the generic INTERNAL_ERROR; they never expose internal details.

Rate limits

Rate limits apply per API key across /api. Exceeding a limit returns 429 RATE_LIMIT_EXCEEDED with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and the matching X-RateLimit-* headers. One documented endpoint limit: avatar upload and update (POST/PUT /api/avatars) allow 5 requests per minute per key. Back off on 429 and retry after the reset window.

Idempotency and terminal states

Session IDs are server-generated; there are no client idempotency keys.
POST /api/sessions/{id}/end and DELETE /api/sessions/{id} may return 202 instead of 200. A 202 means the request was accepted but session cleanup is still pending (pending: true). Poll GET /api/sessions/{id} until session.status becomes ENDED (or the record disappears after delete).
Repeating POST /api/sessions/{id}/end while cleanup runs is safe and idempotent; once ended, further calls return SESSION_ALREADY_ENDED.
ingestion.wsToken is single-use and expires after 15 minutes. A dropped WebSocket or expired token requires POST /api/sessions/{id}/reconnect - the status endpoint never returns tokens.

API Reference

Sessions

Avatars

API Keys

Base URL

Authentication

Scopes

Error envelope

Common error codes

Rate limits

Idempotency and terminal states

​Base URL

​Authentication

​Scopes

​Error envelope

​Common error codes

​Rate limits

​Idempotency and terminal states

Base URL

Authentication

Scopes

Error envelope

Common error codes

Rate limits

Idempotency and terminal states