Get startedQuickstart

Voice Agent API

Create an agent and start a live conversation

Agents is in beta. Request and response shapes on /v1/agents/* may still change before general availability. See the overview for details.

A voice agent holds a real-time spoken conversation: it listens, reasons with an LLM, and speaks back. This page takes you from an API key to a live agent you can talk to, then points to telephony and knowledge-base guides.

1

Get your API key

  1. Sign up at platform.speechify.ai
  2. Go to API Keys
  3. Copy your default API key
$export SPEECHIFY_API_KEY="your-api-key-here"
2

Create an agent

An agent bundles a prompt, a voice, and a default LLM. Agent voice IDs come from the curated agent voice catalog (GET /v1/agents/voices) - a different, smaller set than the Build TTS catalog. Built-in examples: sabrina (default), carly, dominic, lyla.

POST
/v1/agents
1curl -X POST https://api.speechify.ai/v1/agents \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Example name",
6  "prompt": "example",
7  "first_message": "example",
8  "tts": {
9    "voice_id": "voice_01jqr8x9zg5k2m3n4p5q6r7s8t",
10    "speed": 0.5
11  },
12  "slug": "example",
13  "language": "en-US",
14  "additional_languages": [
15    {
16      "language": "es",
17      "voice_id": "sofia",
18      "first_message": "¡Hola! ¿En qué puedo ayudarte?"
19    }
20  ],
21  "llm": {
22    "provider": "openai",
23    "model": "gpt-4.1",
24    "base_url": "example",
25    "credential_id": "cred_01jqr8x9zg5k2m3n4p5q6r7s8t",
26    "extra_body": {},
27    "temperature": 0
28  },
29  "stt": {
30    "override": "whisper-v3"
31  },
32  "turn_handling": {
33    "response_delay_seconds": 0,
34    "inactivity_timeout_seconds": 30
35  },
36  "memory": {
37    "enabled": true,
38    "retention_days": 0
39  },
40  "navigator": {
41    "enabled": true,
42    "ivr_cache_enabled": true
43  },
44  "background_noise": {
45    "preset": "office",
46    "volume": 0
47  },
48  "widget_config": {
49    "version": 1,
50    "style": "pill",
51    "theme": "dark",
52    "avatar": {
53      "type": "orb",
54      "image_url": "example",
55      "orb_color_1": "example",
56      "orb_color_2": "example"
57    },
58    "text": {
59      "start_call": "example",
60      "end_call": "example",
61      "listening": "example",
62      "thinking": "example",
63      "speaking": "example"
64    },
65    "terms": {
66      "enabled": true,
67      "content": "example"
68    },
69    "transcript": {
70      "enabled": true
71    }
72  },
73  "is_public": true,
74  "allowed_origins": [
75    "example"
76  ],
77  "hostname_allowlist": [
78    "example"
79  ],
80  "webhook_url": "https://example.com/webhook",
81  "webhook_secret": "whsec_01jqr8x9zg5k2m3n4p5q6r7s8t",
82  "amd": {
83    "enabled": true,
84    "on_voicemail": {
85      "action": "hangup",
86      "message": "example"
87    },
88    "on_ivr": {
89      "action": "proceed"
90    },
91    "on_unavailable": {
92      "action": "hangup"
93    },
94    "tuning": {
95      "human_speech_threshold_seconds": 0.5,
96      "no_speech_threshold_seconds": 1,
97      "timeout_seconds": 5,
98      "classification_prompt": "example"
99    }
100  },
101  "save_audio_recording": true
102}'
Try it

The response includes the agent’s id, which you pass to every agent-scoped call.

3

Start a conversation

POST /v1/agents/{id}/conversations provisions a realtime session and returns a short-lived token. The caller connects directly to the session; audio never flows through our server.

4

Embed it

The fastest way to hear the agent on a page is the drop-in web component:

1<script src="https://cdn.speechify.ai/widget/agents.js"></script>
2<speechify-agent agent-id="<agent.id>"></speechify-agent>

Enable the Public toggle on the agent’s Embed tab and add your origin to the allowlist. Full details in Embed.

What an agent bundles

PartSet by
PromptPOST /v1/agents (prompt)
VoiceAn agent voice ID from GET /v1/agents/voices
LLMThe agent’s default model
KnowledgeAttach a knowledge base (see below)

Cap call length

Set max_call_duration_seconds on an agent to hard-cap the wall-clock length of a single call. When a live call reaches the cap, the agent ends it automatically - useful for bounding the cost of a runaway call. Set it when you create or update an agent:

$curl -X PATCH https://api.speechify.ai/v1/agents/<agent.id> \
>  -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "max_call_duration_seconds": 600 }'

null (the default) means no per-agent cap: the call is bounded only by your plan’s call ceiling. That ceiling is also the hard upper bound for the field, so a value above it is rejected. In the dashboard the same control lives on the agent’s Advanced tab under Max call duration, entered in minutes.

Next steps

Voice Agent Quickstart

The shortest path to a live test call.

Telephony

Give an agent a phone number for inbound and outbound calls.

Knowledge base

Ground answers in your own content.

API Reference

Full endpoint documentation.