API · Sessions

Direct a live session

Change the shot while a session runs: cut to a close-up for an important moment, go back to the automatic camera, or move the avatar to another room.

Change the stage

POST/v1/sessions/{session_id}/stage

Field	Description
`camera`	`far` (chest up), `mid` (shoulders and face) or `close` (face). `auto` hands the camera back to the automatic director.
`hold`	Default `true`: the camera stays where you put it until you send `auto`. `false`: a one-off cut; the automatic camera carries on afterwards.
`backdrop`	A backdrop id from the catalog, or `none` for plain.

Send any of the three. The cut uses the same short dip to black as the automatic camera, and the answer comes once the new stage is on screen.

curl -X POST https://talk.selviaai.com/v1/sessions/SESSION_ID/stage \
  -H "Authorization: Bearer $SELVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"camera": "close"}'

Response

{
  "avatar_id": "face12",
  "camera": "close",
  "camera_mode": "hold",
  "cameras": ["far", "mid", "close"],
  "backdrop": "library"
}

Read the stage

GET/v1/sessions/{session_id}/stage

What is on screen now, and every camera and backdrop this session can use.

Response

{
  "avatar_id": "face12",
  "camera": "mid",
  "camera_mode": "auto",
  "cameras": ["far", "mid", "close"],
  "backdrop": "library",
  "available": {
    "cameras": ["far", "mid", "close", "auto"],
    "backdrops": ["none", "brightoffice", "cafe", "library", "lounge", "office", "salon"]
  }
}

Good to know

It works on every kind of session: ones you started with the API, website-widget visitors and console calls. Your Selvia AI assistant never changes the stage by itself during a conversation; only your calls do. The change lasts for this session only: the agent's saved studio settings stay as they are.

In render mode you can also send the same changes over your socket, timed to a moment in the speech: see Streaming protocol. Errors: 404 session_not_found for a session that isn't live, 422 invalid_stage for an unknown camera or backdrop.