API · Get started

Quickstart

From an API key to a live avatar conversation on your own page, in five steps.

Before you start

You need a Selvia AI account with at least one agent. Every account can use the API; the free plan includes 60 minutes a month. The examples use cURL, Python (requests) and JavaScript (Node 18 or later).

Steps

  1. 1

    Create an API key

    In the console, open Developers, choose what the key may do, and click Create key. Copy it straight away: it is shown once. Keep it on your server, for example in an environment variable:

    export SELVIA_API_KEY="sk_live_…"
  2. 2

    Pick an agent

    List your agents and note the id of the one to start. You can also create one from code.

    curl https://talk.selviaai.com/v1/agent/list \
  -H "Authorization: Bearer $SELVIA_API_KEY"
  3. 3

    Start a session

    Start a live session for that agent. It is ready in a second or two when the avatar is warm.

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

    Response · 201

    {
  "session_id": "1b913015-776e-4700-b17f-f1a9cdc8338f",
  "status": "active",
  "mode": "conversation",
  "agent_id": 7,
  "player_url": "https://…selviaai.com:10000/?…&sid=1b913015-776e-4700-b17f-f1a9cdc8338f",
  "max_session_seconds": null,
  "created_at": "2026-10-17T10:55:15Z"
}
  4. 4

    Show the player to your visitor

    Put player_url in an iframe on your page, or open it as a link. The visitor allows the microphone and talks to the avatar. Open it within about 90 seconds: a session that nobody watches for 90 seconds is ended.

    HTML

    <iframe
  src="PLAYER_URL"
  allow="microphone; autoplay; fullscreen"
  style="width: 100%; aspect-ratio: 16 / 9; border: 0; border-radius: 12px">
</iframe>
  5. 5

    Stop the session

    A session runs, and is billed, until you stop it. Free accounts are capped at 5 minutes per session.

    curl -X POST https://talk.selviaai.com/v1/sessions/SESSION_ID/stop \
  -H "Authorization: Bearer $SELVIA_API_KEY"

    Response

    {
  "session_id": "1b913015-776e-4700-b17f-f1a9cdc8338f",
  "status": "ended",
  "mode": "conversation",
  "end_reason": "api_stop",
  "duration_seconds": 184
}
Each player_url belongs to its own session. When the session ends, the page disconnects and can't be reused; start a new session for the next visitor.

Next steps

Start a session →

Every option: another face, voice or studio look for one session.

Render mode →

Let your own voice agent do the talking.

Direct a live session →

Cut the camera or swap the backdrop mid-conversation.

Create & configure an agent →

Set up a new agent without opening the console.