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  "llm": {
15    "provider": "openai",
16    "model": "gpt-4o",
17    "base_url": "example",
18    "credential_id": "cred_01jqr8x9zg5k2m3n4p5q6r7s8t",
19    "extra_body": {},
20    "temperature": 0
21  },
22  "stt": {
23    "override": "whisper-v3"
24  },
25  "turn_handling": {
26    "response_delay_seconds": 0,
27    "inactivity_timeout_seconds": 30
28  },
29  "memory": {
30    "enabled": true,
31    "retention_days": 0
32  },
33  "navigator": {
34    "enabled": true,
35    "ivr_cache_enabled": true
36  },
37  "background_noise": {
38    "preset": "office",
39    "volume": 0
40  },
41  "widget_config": {
42    "version": 1,
43    "style": "pill",
44    "theme": "dark",
45    "avatar": {
46      "type": "orb",
47      "image_url": "example",
48      "orb_color_1": "example",
49      "orb_color_2": "example"
50    },
51    "text": {
52      "start_call": "example",
53      "end_call": "example",
54      "listening": "example",
55      "thinking": "example",
56      "speaking": "example"
57    },
58    "terms": {
59      "enabled": true,
60      "content": "example"
61    },
62    "transcript": {
63      "enabled": true
64    }
65  },
66  "is_public": true,
67  "allowed_origins": [
68    "example"
69  ],
70  "hostname_allowlist": [
71    "example"
72  ],
73  "webhook_url": "https://example.com/webhook",
74  "webhook_secret": "whsec_01jqr8x9zg5k2m3n4p5q6r7s8t",
75  "amd": {
76    "enabled": true,
77    "on_voicemail": {
78      "action": "hangup",
79      "message": "example"
80    },
81    "on_ivr": {
82      "action": "proceed"
83    },
84    "on_unavailable": {
85      "action": "hangup"
86    },
87    "tuning": {
88      "human_speech_threshold_seconds": 0.5,
89      "no_speech_threshold_seconds": 1,
90      "timeout_seconds": 5,
91      "classification_prompt": "example"
92    }
93  },
94  "save_audio_recording": true
95}'
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://api.speechify.ai/v1/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)

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.