POST /launch

Launches a voice-agent session and returns a room URL to connect to.

POST https://agents.api.respeecher.com/launch

Headers

Header	Value	Required
`Authorization`	`Bearer <YOUR_API_KEY>`	Yes
`Content-Type`	`application/json`	Yes

Request body

A JSON object. You must provide either system_prompt or preset.

Field	Type	Default	Description
`system_prompt`	string	—	The agent's system prompt. Required unless `preset` is given.
`preset`	string	—	Name of a server-configured prompt to use instead of `system_prompt`.
`voice_id`	string	`marta`	The TTS voice the agent speaks with. See Available voices.
`client_tools`	array	`[]`	Client-side tools the agent may call. See Client tools.
`transport`	string	`daily`	How the client connects: `daily` (returns a room `url`) or `websocket` (returns a `wsUrl`). See Transports.
`llm_temperature`	number	—	LLM sampling temperature, `0`–`1` inclusive. Omit to use the model default.
`voice_sampling_params`	object	`{}`	TTS sampling parameters. See the respective page on the Respeecher Space docs.
`vad_settings`	object	`{}`	Voice-activity-detection tuning (speech/turn-taking sensitivity). See VAD settings.
`user_turn_max_silence_secs`	number	`1.5`	Maximum time, in seconds, the agent waits for the user to continue after they go quiet before replying — an upper bound on the turn-taking model's patience. Counted from the end of speech, so it must exceed `vad_settings.stop_secs`; at most `5`.

note

system_prompt takes precedence: if both system_prompt and preset are provided, the prompt is used and the preset is ignored.

note

Unknown fields are rejected with 422 — check names against this table.

Available voices

Call GET /voices for the authoritative list of voices your API key can use — languages beyond the ones below can be enabled per key.

The voices below are available to every key: any voice from the Respeecher Space Ukrainian model, as well as select voices from the English model.

note

Currently, voices for other languages have a bit higher latency than the English ones.

English

marta
amara
tom
neal
christian
victoria-commercial
victoria-cyber
victoria-voiceover
samantha
bill
abby
theo

Ukrainian

kseniia-conversation
roksolana-conversation
olesia-conversation
olesia-media
olesia-announcement
mariia-audiobook
oleksandr-radio
oleksandr-commercial
yevhen-commercial
yevhen-audiobook
dmytro-conversation
ihoreo-conversation
ihoreo-media

Client tools

client_tools is an array of tool definitions the model can call during the conversation; your client handles the calls and returns results (see Quickstart §3).

Each entry has the shape:

{
  "function": {
    "name": "searchProducts",
    "description": "Search the catalog by name or brand.",
    "parameters": {
      "properties": {
        "query": { "type": "string", "description": "Search query" }
      },
      "required": ["query"]
    }
  }
}

parameters follows JSON Schema (properties + required).
Tools with no inputs may omit parameters entirely.

VAD settings

vad_settings tunes the voice activity detector — how readily the agent decides the user started speaking (which also interrupts the agent mid-sentence) and how much silence counts as a pause.

Field	Type	Range	Default	Description
`confidence`	number	`0`–`1`	`0.7`	Minimum speech probability for audio to count as speech. Raise to make detection stricter, lower to pick up softer or distant speakers.
`start_secs`	number	≥ `0`	`0.2`	How long speech must persist before the user counts as speaking. Raise to make the agent harder to interrupt with short sounds.
`stop_secs`	number	≥ `0`	`0.2`	How much silence ends a burst of speech. End of turn is decided by a turn-taking model on top of this, so this mostly sets the minimum pause before the agent may reply. Raising it adds response delay.
`min_volume`	number	`0`–`1`	`0.6`	Minimum normalized loudness for audio to count as speech. Lower to admit quieter speakers, raise to gate out background chatter. `0` disables the volume gate.

To bound the total wait after the user goes quiet — including the extra time the turn-taking model may hold the turn open — use the top-level user_turn_max_silence_secs field.

note

Omitted fields are filled in with default values, which may change over time as we tune the default experience.

Transports

Each launch spawns one bot, so the URL you get back is for a single session — reusing it after that call ends won't reconnect you to an agent. The transport field selects how your client connects:

daily (default) — the response contains a Daily room url. Connect with a Pipecat client using the Daily transport (see the Quickstart).
websocket — the response contains a wsUrl bound to one spawned bot and a single connection, using the WebSocket transport (protobuf serializer).

note

A session is closed after 15 minutes of inactivity — connect within that window.

Response

200 OK. The shape depends on transport:

daily (default):

{ "url": "https://respeecher.daily.co/<room>" }

websocket:

{ "wsUrl": "wss://agents.api.respeecher.com/ws/<token>" }

Errors

Status	Meaning
`401 Unauthorized`	Missing or invalid bearer token.
`404 Not Found`	The named `preset` does not exist, or the `voice_id` is unknown or not available to your key.
`422 Unprocessable Entity`	Neither `system_prompt` nor `preset` was provided (or the body failed validation).
`500 Internal Server Error`	The session could not be created.

Examples

curl

curl -X POST https://agents.api.respeecher.com/launch \
  -H "Authorization: Bearer $RESPEECHER_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a friendly assistant. Keep replies short.",
    "voice_id": "ihoreo-conversation"
  }'

Launch with a preset

curl -X POST https://agents.api.respeecher.com/launch \
  -H "Authorization: Bearer $RESPEECHER_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preset": "ecom-ua" }'

fetch (from your backend)

const res = await fetch("https://agents.api.respeecher.com/launch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RESPEECHER_AGENTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    system_prompt: "You are a shopping assistant.",
    voice_id: "ihoreo-conversation",
    client_tools: tools,
  }),
});
const { url } = await res.json();

WebSocket transport with tuning

curl -X POST https://agents.api.respeecher.com/launch \
  -H "Authorization: Bearer $RESPEECHER_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a friendly assistant.",
    "voice_id": "ihoreo-conversation",
    "transport": "websocket",
    "llm_temperature": 0.6,
    "voice_sampling_params": { "temperature": 0.7 }
  }'
# => {"wsUrl":"wss://agents.api.respeecher.com/ws/<token>"}

Headers​

Request body​

Available voices​

English​

Ukrainian​

Client tools​

VAD settings​

Transports​

Response​

Errors​

Examples​

curl​

Launch with a preset​

fetch (from your backend)​

WebSocket transport with tuning​

Headers

Request body

Available voices

English

Ukrainian

Client tools

VAD settings

Transports

Response

Errors

Examples

curl

Launch with a preset

fetch (from your backend)

WebSocket transport with tuning