API · Render mode

Render mode: bring your own agent

Keep your own voice agent and give it a face. You send the avatar's speech; it speaks it on screen with matching lips, expressions and body language, and the visitor hears it in the video.

When to use it

  • •You already run a voice agent: your own speech recognition, language model and voice, or a hosted agent platform.
  • •You need control over the conversation that a ready-made assistant doesn't give: your own prompts, tools, turn-taking or compliance rules.
  • •You want the avatar as one part of a bigger system.

If you don't have an agent of your own, a conversation session does all of it for you: listening, thinking, knowledge, memory and voice.

How it works

visitor ──speaks──▶ your agent (speech recognition → language model → voice)
                         │
                         │  speech audio, or text, over ws_url
                         ▼
               Selvia AI avatar  ──video with the speech──▶  visitor (player_url)
  1. 1

    Start a render session

    POST /v1/sessions with "mode": "render". The answer has player_url for the visitor and ws_url for your server.

  2. 2

    Show the player

    Put player_url in an iframe. It needs no microphone: your agent hears the visitor its own way.

  3. 3

    Stream the speech

    Connect your server to ws_url and send each reply as it is produced: your own voice's audio, or text that we voice with the agent's voice. See Streaming protocol.

  4. 4

    Stop it

    POST /v1/sessions/{id}/stop when the conversation is over.

Audio or text

  • •Your own voice (the usual way): send your speech engine's audio as it streams. Add the words it says as text and the avatar picks a matching expression for each sentence.
  • •Text: send the reply's text and the avatar speaks it with the agent's voice from the console. Free voices cost nothing extra; premium voices are charged per character, as in conversations.

Price

$0.025 per minute, from start to stop, rounded up to the whole minute. In text mode, premium voices add their per-character charge. See Limits & pricing.

Rules of thumb

  • •The visitor must hear the speech from our video. Don't also play it on your page: it would drift from the lips.
  • •Send audio faster than real time. If it arrives slower than it plays, voice and lips stutter and you get an audio_starvation warning.
  • •Send text sentence by sentence as your language model streams it, not whole paragraphs: the avatar starts after the first sentence.
  • •The avatar never speaks on its own in render mode, not even a greeting. Send one if you want it.

Next

Streaming protocol →

Commands, events, audio format and close codes.

Expressions →

Choose how the avatar looks while it speaks.

Example: stream your own voice →

A complete Python and JavaScript client.

Direct a live session →

Camera cuts and backdrops, also timed from the socket.