API · Set up agents

Create & configure an agent

An agent is your avatar assistant: its face, voice, languages, studio and what it knows. These are the same settings as in the console, so anything you set here shows there, and the other way round.

Create an agent

POST/v1/agent/create

Field	Description
`name`	Required. What the avatar calls itself.
`avatar_id`	The face, e.g. `face09`. Default `face01`. See the catalog.
`voice_id`	The voice. It should suit the face. Default `af_bella`.
`tts_primary`	The voice provider: `kokoro` (free, the default) or a premium one: `inworld`, `inworld-flash`, `elevenlabs`, `elevenlabs-flash`, `cartesia`.
`languages`	`{"main": "en", "also": ["es", "fr"]}`: the language it greets in, and the others it switches to when a visitor uses them.
`studio`	`backdrop` (a backdrop id or `null` for plain), `cameras` (any of `far`, `mid`, `close`), `face_light` (0.5 to 1.5).
`website_url`	Your website, used to teach it your business.
`system_prompt`	Optional instructions written by you, instead of building them from your website.
`concurrency_limit`	How many conversations it may hold at once. Default 1.

curl -X POST https://talk.selviaai.com/v1/agent/create \
  -H "Authorization: Bearer $SELVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ava",
    "website_url": "https://bloomhair.example",
    "avatar_id": "face09",
    "voice_id": "af_heart",
    "languages": { "main": "en", "also": ["es"] },
    "studio": { "backdrop": "salon", "cameras": ["far", "mid", "close"] }
  }'

The answer is the whole agent, with its id. It can take a session straight away.

Change it

PATCH/v1/agent/{agent_id}

Send only what changes. Besides the fields above: welcome_message (its first words, up to 300 characters), fillers_enabled (short "let me see" sounds while it thinks), name, status. A studio change merges with what is saved, so {"studio": {"face_light": 1.15}} leaves the backdrop and cameras alone. Changes show on the next session, not one already running.

curl -X PATCH https://talk.selviaai.com/v1/agent/42 \
  -H "Authorization: Bearer $SELVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome_message": "Hi, I'\''m Ava from Bloom. How can I help?", "studio": {"face_light": 1.15}}'

List, read, delete

GET/v1/agent/list

GET/v1/agent/{agent_id}

DELETE/v1/agent/{agent_id}?confirm=true

Deleting needs a key with the delete permission and confirm=true. It removes the agent and its knowledge; it can't be undone.

Free plan

A free account has one agent and the free voices (kokoro). Creating a second agent or choosing a premium voice answers 402 with agent_limit or paid_feature; adding funds in the console removes both limits.