API · Sessions

Start a session

Start a live avatar for one visitor. Pick the mode, and optionally another face, voice or look for this session only; the agent's saved settings stay as they are.

Request

POSThttps://talk.selviaai.com/v1/sessions

Needs a key with the sessions permission.

Field	Type	Description
`agent_id`	integer, required	The agent to start. List yours with GET /v1/agent/list.
`mode`	`conversation \| render`	Default `conversation`. `render`: your own agent does the talking (render mode).
`avatar_id`	string	Another face for this session, e.g. `face12`. See the catalog.
`voice_id`	string	Another voice for this session. Premium voices need a paid account.
`look`	object	Studio look for this session, laid over the agent's: `backdrop` (a backdrop id, or `null` for plain), `cameras` (any of `far`, `mid`, `close`), `camera` (start on `far`, `mid`, `close` or `auto`), `face_light` (0.5 to 1.5).

Unknown fields are refused, so a typo answers 422 instead of being ignored.

curl -X POST https://talk.selviaai.com/v1/sessions \
  -H "Authorization: Bearer $SELVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 7,
    "mode": "conversation",
    "avatar_id": "face12",
    "look": { "backdrop": "library", "camera": "mid", "face_light": 1.1 }
  }'

The voice must suit the face

As in the console, a session can't pair a man's face with a woman's voice or the other way round: changing the face to one whose voice no longer fits answers 422 voice_face_mismatch. Pass a voice_id that suits the new face.

Response

Field	Description
`session_id`	Use it to check, stop or direct the session.
`player_url`	The page your visitor watches. It works for this session only.
`ws_url`	Render mode only. Where your server streams the avatar's speech. It contains a secret token: keep it on your server.
`max_session_seconds`	The session ends at this age (300 on the free plan). `null`: it runs until you stop it.

Conversation · 201

{
  "session_id": "93d59ff0-3708-4cb8-bf1f-0b955b8e6a4b",
  "status": "active",
  "mode": "conversation",
  "agent_id": 7,
  "player_url": "https://…selviaai.com:10000/?…&sid=93d59ff0-3708-4cb8-bf1f-0b955b8e6a4b",
  "max_session_seconds": null,
  "created_at": "2026-10-17T14:41:55Z"
}

Render mode · 201

{
  "session_id": "ce681d63-47de-4ba2-ad5b-cf008ea50be5",
  "status": "active",
  "mode": "render",
  "agent_id": 7,
  "player_url": "https://…selviaai.com:10000/render.html?sid=ce681d63-…",
  "ws_url": "wss://…selviaai.com/ws/render/1?token=…",
  "max_session_seconds": null,
  "created_at": "2026-10-17T14:41:45Z"
}

Show it to the visitor

HTML

<!-- conversation: the visitor talks to the avatar -->
<iframe src="PLAYER_URL" allow="microphone; autoplay; fullscreen"
        style="width:100%; aspect-ratio:16/9; border:0"></iframe>

<!-- render mode: no microphone needed -->
<iframe src="PLAYER_URL" allow="autoplay; fullscreen"
        style="width:100%; aspect-ratio:16/9; border:0"></iframe>

The visitor hears the avatar from the player. Browsers may ask for one tap before they play sound; the player shows a play button when that happens. Open the page within about 90 seconds of starting the session.

Errors

Status	code	Meaning
402	`insufficient_balance`	A paid account with no balance left. Top up in the console.
402	`free_minutes_exhausted`	A free account used its 60 minutes this month.
402	`free_concurrency`	A free account already has a session running.
402	`paid_feature`	A premium voice on a free account.
404	`agent_not_found`	No agent with this id in your account.
409	`agent_building`	The agent's knowledge is being built (conversation mode). Try again in a few minutes.
409	`concurrency_limit`	The agent already has as many sessions as its concurrency_limit allows.
422	`voice_face_mismatch`	The voice doesn't suit the face.
422	`unknown_avatar / invalid_look`	A face, backdrop or camera that doesn't exist.
503	`no_capacity`	Every avatar is busy. Try again shortly.

The body is {"detail": {"code": "…", "message": "…"}}. See Errors.