Getting Started

Build your first voice agent in under 5 minutes.

1. Get an API Key

Sign up at the Developer Portal and create an API key. Keys use the plabs_ prefix.

export PH0NY_API_KEY="plabs_your_key_here"

2. Create an Agent

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/agents \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "systemPrompt": "You are a helpful voice assistant. Keep responses concise and conversational.",
    "firstMessage": "Hey there! How can I help you today?",
    "ttsProvider": "cartesia",
    "llmProvider": "openai"
  }'

Response:

{
  "id": "agent_abc123",
  "name": "My First Agent",
  "status": "active",
  "ttsProvider": "cartesia",
  "llmProvider": "openai",
  "createdAt": "2026-03-21T00:00:00.000Z"
}

3. Chat with Your Agent

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/agents/agent_abc123/chat \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What can you help me with?"
  }'

Response:

{
  "reply": "I can help with all sorts of things! Ask me questions, ...",
  "conversationId": "conv_xyz789",
  "turnIndex": 0
}

4. Synthesize Speech

Generate audio from text using your agent's voice:

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/agents/agent_abc123/speak \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world! This is my voice agent speaking.",
    "format": "mp3"
  }' \
  --output hello.mp3

5. Connect a Phone Number (Twilio)

To receive real phone calls, create a Twilio session:

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/sessions/twilio \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "from": "+18005551234",
    "to": "+19005551234"
  }'

The response includes TwiML that Twilio uses to connect the caller to your agent's WebSocket stream.

Using the SDK

Install the SDK for a typed client:

pnpm add @ph0ny/sdk

import { createVoiceClient } from '@ph0ny/sdk'

const client = createVoiceClient({
  apiKey: process.env.PH0NY_API_KEY!,
})

// Create agent
const agent = await client.agents.create({
  name: 'My Agent',
  systemPrompt: 'You are a helpful assistant.',
  ttsProvider: 'cartesia',
  llmProvider: 'openai',
})

// Chat
const response = await client.agents.chat(agent.id, {
  message: 'Hello!',
})

console.log(response.reply)

Next Steps

• Authentication — API keys, Bearer tokens, BYOK
• Agents — system prompts, tools, instances, audience groups
• Voice Cloning — clone voices from audio samples
• Knowledge (RAG) — ingest documents and enable retrieval
• API Reference — full endpoint documentation