# Selvia AI API

> Live, realistic 3D avatars that talk with your visitors. With one API key your code, or your
> AI agent, can create and set up avatar agents and run live sessions: everything the console does.

- Base URL: https://talk.selviaai.com/v1
- Auth: `Authorization: Bearer sk_live_...`, from a server only. Keys are made in the console
  (console.selviaai.com, Developers) with permissions: read, setup, sessions, delete.
- Deleting anything needs `?confirm=true` and a key with the delete permission.
- Full reference (OpenAPI): https://talk.selviaai.com/v1/openapi.json  · interactive: https://talk.selviaai.com/v1/docs

## Quick start

1. Pick or make an agent: `GET /v1/agent/list`, or `POST /v1/agent/create`.
2. Choose how it looks and sounds: `GET /v1/catalog/faces` (id, words, stills),
   `GET /v1/catalog/backdrops`, `GET /v1/catalog/cameras`, `GET /v1/voices/{provider}?language=en`
   (providers: kokoro is free; inworld, inworld-flash, elevenlabs, elevenlabs-flash, cartesia
   are premium). Save choices with `PATCH /v1/agent/{agent_id}`.
3. Start a session: `POST /v1/sessions` with `{"agent_id": 7}`. Show `player_url` to your visitor
   (an iframe or a link).
4. End it: `POST /v1/sessions/{session_id}/stop`. A session runs, and is billed, until you stop it.
   Free accounts: 5 minutes per session at most. A session nobody watches for 90 seconds is ended.

## Sessions

- `mode: "conversation"` (default): the agent talks with the visitor on its own, with its prompt,
  knowledge and voice.
- `mode: "render"`: your own agent does the talking. The answer also has `ws_url`; your server
  streams the avatar's speech there (below). The visitor watches `player_url` and hears the speech
  inside the video. `ws_url` holds a secret token: keep it on your server.
- Per-session overrides on `POST /v1/sessions`: `avatar_id`, `voice_id`, and `look`
  (`backdrop`, `cameras`, `camera`, `face_light` 0.5 to 1.5). The agent's saved settings stay as they are.
- `GET /v1/sessions` lists the account's live sessions of every kind (API, website widget, console).
- Direct a live session: `POST /v1/sessions/{id}/stage` with `{"camera": "close"}` (held until you
  send `"auto"`, unless `"hold": false`) or `{"backdrop": "library"}`. `GET` it to read the stage.

## Pricing

- Conversation: $0.030 per minute. Render: $0.025 per minute.
  Minutes are counted from start to stop, rounded up per session.
- Premium voices are charged per character on top. The free voices cost nothing extra.

## Render mode: streaming speech to ws_url

Connect from your server: `wss://...` exactly as returned in `ws_url` (add `&sample_rate=24000`
if needed). One socket per session; a new one replaces the old.

Audio: PCM signed 16-bit little-endian, mono, 16000, 22050, 24000 (default), 44100 or 48000 Hz.
Send it faster than real time, in pieces of any size, as base64 in `agent.speak` or as binary
frames (max 1 MB each). At most 120 s of audio may wait to play (`queue_full` beyond that).
Send whole samples: carry an odd byte over to the next piece.

Commands (JSON, each may carry an `event_id`):
- `agent.speak` {"audio": base64, "text"?: what it says}: append to the current utterance.
- `agent.speak_end`: seal it. Utterances play one after another.
- `agent.speak_text` {"text", "cue"?}: we voice the text with the agent's voice (premium voices
  are billed per character). Send it sentence by sentence as your LLM streams.
- `agent.interrupt`: stop now and drop everything queued.
- `agent.start_listening` / `agent.stop_listening`: the listening look between utterances.
- `agent.cue` {"cue", "intensity"?, "at_seconds"?}: an expression from that moment on.
- `stage.camera`, `stage.backdrop`, `stage.get` (optional `at_seconds`): direct the stage.
- `session.configure` {"sample_rate"} before the first audio; `session.keep_alive`.

Events: `session.state_updated`, `agent.state_updated` (idle, listening, talking),
`agent.speak_started`, `agent.speak_ended`, `agent.speak_interrupted`,
`agent.audio_buffer_cleared`, `warning` (audio_starvation), `error`
(invalid_request_error, queue_full, tts_error). Utterance events carry `source_event_id`.
Close codes: 4003 bad or expired token, 4001 session ended, 4002 replaced, 4000 bad sample_rate.

Expressions: apology, authority, concern, confidence, curiosity, decline, discomfort, enthusiasm,
playful, question, reflective, surprise, thinking, thoughtful, warmth, welcome. Set them three
ways: send the audio's `text` and we choose per sentence; put a tag like `[warmth]` in the text
(remove tags before your own speech engine); or send `agent.cue` with `at_seconds`.

The visitor must hear the speech from our video. Don't also play it on your page.
The avatar never speaks on its own in render mode: send a greeting if you want one.

## Every route

- POST /v1/agent/create: Create Agent
- GET /v1/agent/has-agents: Check Has Agents
- GET /v1/agent/list: List Agents
- GET /v1/agent/{agent_id}: Get Agent
- DELETE /v1/agent/{agent_id}: Delete Agent
- PATCH /v1/agent/{agent_id}: Update Agent
- POST /v1/agent/{agent_id}/add-page: Add Page
- GET /v1/agent/{agent_id}/brain-status: Get Brain Status
- POST /v1/agent/{agent_id}/duplicate: Duplicate Agent
- GET /v1/agent/{agent_id}/embed: Get Embed Config
- PATCH /v1/agent/{agent_id}/embed: Update Embed Config
- POST /v1/agent/{agent_id}/embed/apply-to-all: Apply Embed To All
- POST /v1/agent/{agent_id}/embed/regenerate: Regenerate Embed Key
- GET /v1/agent/{agent_id}/extract-links: Extract Links
- POST /v1/agent/{agent_id}/generate-brain: Generate Brain
- GET /v1/agent/{agent_id}/kb-sections: List Kb Sections
- POST /v1/agent/{agent_id}/kb-sections: Add Kb Section
- PATCH /v1/agent/{agent_id}/kb-sections/{topic}: Edit Kb Section
- DELETE /v1/agent/{agent_id}/kb-sections/{topic}: Delete Kb Section
- DELETE /v1/agent/{agent_id}/pages: Clear Pages
- GET /v1/agent/{agent_id}/pages/list: List Pages
- PATCH /v1/agent/{agent_id}/pages/{page_id}: Edit Page
- DELETE /v1/agent/{agent_id}/pages/{page_id}: Delete Page
- POST /v1/agent/{agent_id}/preview: Open Preview
- POST /v1/agent/{agent_id}/set-default: Set Default Agent
- POST /v1/agent/{agent_id}/v2/answer: Answer Question
- GET /v1/agent/{agent_id}/v2/behavior: Get Behavior
- PATCH /v1/agent/{agent_id}/v2/behavior: Update Behavior
- GET /v1/agent/{agent_id}/v2/brain: Get Brain
- GET /v1/agent/{agent_id}/v2/completion: Completion Status
- POST /v1/agent/{agent_id}/v2/consolidate: Consolidate Now
- POST /v1/agent/{agent_id}/v2/correction: Correction Preview
- POST /v1/agent/{agent_id}/v2/correction/apply: Correction Apply
- GET /v1/agent/{agent_id}/v2/dynamic-instructions: Get Dynamic Instructions
- PATCH /v1/agent/{agent_id}/v2/dynamic-instructions: Update Dynamic Instructions
- POST /v1/agent/{agent_id}/v2/dynamic-instructions/preview: Preview Dynamic Instructions
- POST /v1/agent/{agent_id}/v2/extract: Extract
- GET /v1/agent/{agent_id}/v2/gaps: List Gaps
- POST /v1/agent/{agent_id}/v2/gaps/{gap_id}/answer: Answer Gap
- POST /v1/agent/{agent_id}/v2/gaps/{gap_id}/dismiss: Dismiss Gap
- POST /v1/agent/{agent_id}/v2/knowledge/ops: Knowledge Ops
- GET /v1/agent/{agent_id}/v2/orphans: List Orphans
- POST /v1/agent/{agent_id}/v2/orphans/resolve: Resolve Orphan
- POST /v1/agent/{agent_id}/v2/probe: Probe
- POST /v1/agent/{agent_id}/v2/questions/state: Question State
- POST /v1/agent/{agent_id}/v2/recompile: Recompile
- POST /v1/agent/{agent_id}/v2/review/resolve: Review Resolve
- GET /v1/agent/{agent_id}/v2/rules: List Rules
- POST /v1/agent/{agent_id}/v2/rules: Create Rule
- PATCH /v1/agent/{agent_id}/v2/rules/{rule_id}: Update Rule
- DELETE /v1/agent/{agent_id}/v2/rules/{rule_id}: Delete Rule
- POST /v1/agent/{agent_id}/v2/schema/generate: Generate Schema
- GET /v1/agent/{agent_id}/visitor-values: Get Visitor Values
- PATCH /v1/agent/{agent_id}/visitor-values: Update Visitor Values
- POST /v1/agent/{agent_id}/visitor-values/preview: Preview Visitor Values
- GET /v1/agent/{agent_id}/visitor-values/secret: Reveal Visitor Signing Secret
- POST /v1/agent/{agent_id}/visitor-values/secret: Rotate Visitor Signing Secret
- GET /v1/billing/by-agent: By Agent
- GET /v1/billing/export/line-items: Export Line Items
- GET /v1/billing/line-items: Line Items
- GET /v1/billing/monthly: Monthly
- GET /v1/billing/plan: Get Plan
- GET /v1/billing/summary: Summary
- GET /v1/billing/voice: Voice
- GET /v1/billing/wallet: Get Wallet
- POST /v1/billing/wallet/portal: Wallet Portal
- POST /v1/billing/wallet/topup: Wallet Topup
- GET /v1/billing/wallet/topup/confirm: Wallet Topup Confirm
- GET /v1/catalog/backdrops: Catalog Backdrops
- GET /v1/catalog/cameras: Catalog Cameras
- GET /v1/catalog/faces: Catalog Faces
- GET /v1/notifications: List Notifications
- GET /v1/notifications/destinations: List Destinations
- POST /v1/notifications/destinations/telegram/connect: Connect Telegram Destination
- GET /v1/notifications/destinations/telegram/connect/{token}: Telegram Destination Connect Status
- POST /v1/notifications/destinations/webhook: Create Webhook Destination
- PATCH /v1/notifications/destinations/{destination_id}: Update Destination
- DELETE /v1/notifications/destinations/{destination_id}: Delete Destination
- GET /v1/notifications/destinations/{destination_id}/deliveries: Webhook Deliveries
- POST /v1/notifications/destinations/{destination_id}/rotate-secret: Rotate Signing Secret
- GET /v1/notifications/destinations/{destination_id}/signing-secret: Reveal Signing Secret
- POST /v1/notifications/destinations/{destination_id}/test: Test Destination
- GET /v1/notifications/prefs/{agent_id}: Get Prefs
- PUT /v1/notifications/prefs/{agent_id}: Update Prefs
- POST /v1/notifications/read: Mark Read
- GET /v1/notifications/rules/{agent_id}: List Rules
- POST /v1/notifications/rules/{agent_id}: Create Rule
- POST /v1/notifications/rules/{agent_id}/builder: Rule Builder Turn
- POST /v1/notifications/rules/{agent_id}/test: Test Rule
- POST /v1/notifications/rules/{agent_id}/test-delivery: Test Rule Delivery
- PUT /v1/notifications/rules/{agent_id}/{rule_id}: Replace Rule
- DELETE /v1/notifications/rules/{agent_id}/{rule_id}: Delete Rule
- POST /v1/notifications/telegram/connect/{agent_id}: Telegram Connect
- POST /v1/notifications/telegram/disconnect/{agent_id}: Telegram Disconnect
- GET /v1/notifications/unread-count: Unread Count
- GET /v1/reports/agents: Reporting Agents
- GET /v1/reports/conversations: List Conversations
- GET /v1/reports/conversations/{conversation_id}: Conversation Detail
- GET /v1/reports/export/conversations: Export Conversations
- GET /v1/reports/export/conversations/{conversation_id}: Export Transcript
- GET /v1/reports/me: Reporting Me
- GET /v1/reports/stats: Stats
- POST /v1/sessions: Create Session
- GET /v1/sessions: List Sessions
- GET /v1/sessions/{session_id}: Get Session
- GET /v1/sessions/{session_id}/stage: Get Stage
- POST /v1/sessions/{session_id}/stage: Change Stage
- POST /v1/sessions/{session_id}/stop: Stop Session
- GET /v1/support/agents: Support Agents
- POST /v1/support/tickets: Create Ticket
- GET /v1/support/tickets: List Tickets
- GET /v1/support/tickets/{ticket_id}: Get Ticket
- POST /v1/support/tickets/{ticket_id}/close: Close Ticket
- POST /v1/support/tickets/{ticket_id}/reply: Reply Ticket
- GET /v1/support/unread-count: Unread Count
- GET /v1/usage/summary: Get Usage Summary
- GET /v1/voices/{provider}: List Voices
- GET /v1/voices/{provider}/{voice_id}/preview: Voice Preview