Create a session

POST

sessions

curl --request POST \
  --url https://api.facemode.io/api/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "avatarId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "room": {
    "type": "livekit",
    "url": "wss://your-project.livekit.cloud",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "name": "demo-room"
  }
}
'

{
  "message": "Session created successfully",
  "session": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "IDLE",
    "startedAt": "2023-11-07T05:31:56Z",
    "roomName": "<string>",
    "room": {
      "type": "livekit",
      "url": "<string>",
      "token": "<string>",
      "name": "<string>"
    },
    "egressType": "livekit",
    "roomUrl": "<string>",
    "roomToken": "<string>",
    "inputProvider": "deepgram"
  },
  "roomName": "<string>",
  "room": {
    "type": "livekit",
    "url": "<string>",
    "token": "<string>",
    "name": "<string>"
  },
  "egressType": "livekit",
  "roomUrl": "<string>",
  "roomToken": "<string>",
  "inputProvider": "deepgram",
  "jobId": "<string>",
  "workerStatus": "PENDING",
  "workerAssignment": {
    "version": 123,
    "provider": "<string>",
    "targetType": "<string>",
    "tier": "<string>",
    "jobId": "<string>",
    "workerId": "<string>",
    "endpointKind": "<string>",
    "websocketBase": "<string>",
    "selectedAt": "2023-11-07T05:31:56Z",
    "assignedAt": "2023-11-07T05:31:56Z",
    "generation": 123,
    "terminationRequestedAt": "2023-11-07T05:31:56Z",
    "terminationReason": "<string>",
    "failure": {
      "code": "<string>",
      "message": "<string>"
    }
  },
  "ingestion": {
    "ready": true,
    "authority": "websocket",
    "url": "wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "wsToken": "<string>",
    "headers": {}
  },
  "greetingVideoUrl": "<string>",
  "idleVideoUrl": "<string>",
  "idleVideoStatus": "<string>"
}

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

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

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

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

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

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

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

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

Creates a session and returns everything needed to start streaming: the session id, the resolved room binding, and ingestion (url + single-use wsToken).

curl -X POST https://api.facemode.io/api/sessions \
  -H "x-api-key: fm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "avatarId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "room": {
      "type": "livekit",
      "url": "wss://your-project.livekit.cloud",
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "name": "demo-room"
    },
    "inputProvider": "deepgram"
  }'

ingestion.wsToken is valid for 15 minutes and is consumed by the first WebSocket connection. Open the socket promptly; if it lapses, call reconnect.

Strict validation rules to be aware of:

Only avatarId, room, livekit_room_id, and inputProvider are accepted - anything else returns REQUEST_FIELD_UNKNOWN with error.details.fields.
waitForIngestion was removed and returns WAIT_FOR_INGESTION_REMOVED.
Legacy byolr, livekitUrl, and livekitToken return ROOM_LEGACY_FIELDS.
avatarId must reference an active platform default or one of your custom avatars, otherwise AVATAR_NOT_FOUND.

Authorizations

x-api-key

string

header

required

FaceMode API key (fm_...).

Body

application/json

avatarId

string<uuid>

required

ID of an active avatar (platform default or owned custom).

room

object

required

Egress room the avatar joins and publishes video into.

Hide child attributes

room.type

enum<string>

required

Room provider.

Available options:

livekit,

daily

room.url

string

required

Room URL. For LiveKit this is the WebSocket URL (wss://...); for Daily, the room URL (https://...daily.co/...).

room.token

string

required

Access token granting the worker permission to join and publish.

room.name

string

Optional room name. For LiveKit, when omitted the name is decoded from the token's video.room claim.

livekit_room_id

string

Optional explicit room name override. Takes precedence over room.name and the LiveKit token claim.

inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

Response

Session created. ingestion.wsToken is short-lived and single-use; store session.id for status, reconnect, and end calls.

message

string

Example:

"Session created successfully"

session

object

Session block embedded in the create response.

Hide child attributes

session.id

string<uuid>

session.status

enum<string>

Session lifecycle state. New sessions start ACTIVE; ended sessions are terminal.

Available options:

IDLE,

ACTIVE,

ENDED

session.startedAt

string<date-time>

session.roomName

string

Resolved room name.

session.room

object

Egress room the avatar joins and publishes video into.

Hide child attributes

session.room.type

enum<string>

required

Room provider.

Available options:

livekit,

daily

session.room.url

string

required

Room URL. For LiveKit this is the WebSocket URL (wss://...); for Daily, the room URL (https://...daily.co/...).

session.room.token

string

required

Access token granting the worker permission to join and publish.

session.room.name

string

Optional room name. For LiveKit, when omitted the name is decoded from the token's video.room claim.

session.egressType

enum<string>

Available options:

livekit,

daily

session.roomUrl

string

Echo of the supplied room URL.

session.roomToken

string

Echo of the supplied room token.

session.inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

roomName

string

room

object

Egress room the avatar joins and publishes video into.

Hide child attributes

room.type

enum<string>

required

Room provider.

Available options:

livekit,

daily

room.url

string

required

Room URL. For LiveKit this is the WebSocket URL (wss://...); for Daily, the room URL (https://...daily.co/...).

room.token

string

required

Access token granting the worker permission to join and publish.

room.name

string

Optional room name. For LiveKit, when omitted the name is decoded from the token's video.room claim.

egressType

enum<string>

Available options:

livekit,

daily

roomUrl

string

roomToken

string

inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

jobId

string | null

Worker job identifier.

workerStatus

enum<string> | null

Media worker lifecycle: PENDING/ASSIGNING mean capacity is still being allocated, ASSIGNED/ACTIVE mean a worker owns the session, ENDING means cleanup is in flight, ENDED/FAILED are terminal.

Available options:

PENDING,

ASSIGNING,

ASSIGNED,

ACTIVE,

ENDING,

ENDED,

FAILED

workerAssignment

object | null

Worker placement metadata for the session. Treat as opaque - fields may change. Useful for correlating jobId with support tickets.

Hide child attributes

workerAssignment.version

integer

workerAssignment.provider

string | null

Compute provider identifier.

workerAssignment.targetType

string | null

workerAssignment.tier

string | null

Capacity tier selected for the session.

workerAssignment.jobId

string | null

workerAssignment.workerId

string | null

workerAssignment.endpointKind

string | null

workerAssignment.websocketBase

string | null

Base WebSocket URL the ingestion.url is derived from.

workerAssignment.selectedAt

string<date-time> | null

workerAssignment.assignedAt

string<date-time> | null

workerAssignment.generation

integer | null

Ownership generation, incremented on each fenced reconnect.

workerAssignment.terminationRequestedAt

string<date-time> | null

workerAssignment.terminationReason

string | null

Why the session is ending, for example user_requested, worker_requested, no_audio_timeout, beta_max_duration, legacy_inactive. Null until termination is requested.

workerAssignment.failure

object | null

Hide child attributes

workerAssignment.failure.code

string

workerAssignment.failure.message

string

ingestion

object

Audio ingestion endpoint for the session. url and wsToken are present only when ready is true.

Hide child attributes

ingestion.ready

boolean

True when the session can accept a WebSocket connection.

ingestion.authority

enum<string>

Ingestion channel; always websocket.

Available options:

websocket

ingestion.url

string

WebSocket URL in the form wss://<host>/ws/{session_id}.

Example:

"wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8"

ingestion.wsToken

string

Short-lived (15 minute), single-use credential. Pass it as the facemode.<wsToken> WebSocket subprotocol, or as the token query parameter.

ingestion.headers

object | null

Optional extra headers required by the ingestion endpoint, when applicable.

Hide child attributes

ingestion.headers.{key}

string

greetingVideoUrl

string

Optional greeting clip the worker can play on join.

idleVideoUrl

string | null

Idle loop clip for the avatar, when rendered.

idleVideoStatus

string

Idle video render state, for example PENDING, READY, or FAILED.

API Reference

Sessions

Avatars

API Keys

Authorizations

Body

Response