Voice Agents quickstart

Get your API key

1. Sign up at console.speechify.ai
2. Go to API Keys
3. Copy your default API key (or create a new one)

$
export SPEECHIFY_API_KEY="your-api-key-here"

Create an agent

An agent bundles a prompt, a voice, and a default LLM. Agent voice IDs come from the curated agent voice catalog, which is a different (smaller) set than the TTS /v1/voices catalog. List the valid IDs with GET /v1/agents/voices — the same slugs are accepted by POST/PATCH /v1/agents. Built-in examples: sabrina (the default), carly, dominic, lyla. Personal/cloned voices are TTS-only and cannot be assigned to an agent.

1
curl -X POST https://api.speechify.ai/v1/agents \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "name": "string",
6
  "voice_id": "string"
7
}'

The response includes the new agent’s id — you’ll pass it to every agent-scoped call below.

Start a conversation

POST /v1/agents/{id}/conversations provisions a realtime voice session, dispatches the agent, and returns a short-lived access token. The caller connects directly to the session with that token — audio never flows through our server.

1
curl -X POST https://api.speechify.ai/v1/agents/agent_01HS.../conversations \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{}'

The response carries the conversation, the LiveKit room, a short-lived token, and the realtime url the caller connects to:

1
{
2
  "conversation": {
3
    "id": "conv_01kr410dd3yrst4chn5kn0t78f",
4
    "agent_id": "agent_01HS...",
5
    "room_name": "conv_01kr410dd3yrst4chn5kn0t78f",
6
    "status": "pending",
7
    "transport": "web",
8
    "created_at": "2024-01-15T09:30:00Z",
9
    "metadata": {},
10
    "message_count": 0
11
  },
12
  "room": "conv_01kr410dd3yrst4chn5kn0t78f",
13
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjb252In0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
14
  "url": "wss://realtime.speechify.ai/conv_01kr410dd3yrst4chn5kn0t78f"
15
}

Embed it on your site

The fastest way to hear your agent on an actual web 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>

That’s the whole integration for a public agent. Enable the Public toggle on the agent’s Embed tab in the console, add the site’s origin to the allowlist, and the widget works unauthenticated — your API key stays on the server.

For private agents, mint a session token on your backend and pass it to the widget via session-token + session-url attributes. Full details in Embed.

Test it from the console

The quickest path to hearing the agent without writing any integration at all: open the agent in the console, click Test Call, and talk.

Create your workspace

Open console.speechify.ai and sign up. Speechify creates a workspace for you automatically — every agent, knowledge base, phone number, and conversation lives inside it.

Create your first agent

Click Agents in the left sidebar, then New agent. Names are for you — the caller never hears them.

Write the prompt

In the Agent tab, fill in the first message, system prompt, voice, and language.

Preview the conversation

Hit Preview, allow microphone access, and talk to the agent live in your browser. Iterate on the prompt until it sounds right.