talk.dev Voice AI API Guidelines

GET    /v1/voices              # List voices
POST   /v1/synthesize          # Text-to-speech
POST   /v1/voices/clone        # Clone voice
GET    /v1/usage               # Usage statistics

POST   /v1/synthesize/stream   # Streaming synthesis
WS     wss://api.talk.dev/v1/stream  # WebSocket for real-time

Authorization: Bearer <jwt-token>
X-API-Key: <api-key>

// Request
POST /v1/synthesize
{
  "text": "Hello world, this is talk.dev voice AI!",
  "voice": "sarah-professional",
  "format": "mp3",
  "emotion": "enthusiastic"
}

// Response
{
  "audio_url": "https://cdn.talk.dev/audio/abc123.mp3",
  "duration": 3.2,
  "characters_used": 43,
  "processing_time": 142,
  "voice_used": "sarah-professional"
}

// Step 1: Initiate cloning
POST /v1/voices/clone
Content-Type: multipart/form-data

{
  "name": "CEO Voice",
  "audio_file": <binary-data>,
  "consent_verified": true
}

// Response
{
  "clone_id": "clone_abc123",
  "status": "processing",
  "estimated_completion": "2024-01-15T10:30:00Z"
}

// Step 2: Check status
GET /v1/voices/clone/clone_abc123

// Response (when complete)
{
  "clone_id": "clone_abc123",
  "status": "completed",
  "voice_id": "custom_ceo_voice_abc123",
  "progress": 100
}

// Step 3: Use cloned voice
POST /v1/synthesize
{
  "text": "Welcome to our quarterly results call",
  "voice": "custom_ceo_voice_abc123"
}

// WebSocket connection
const ws = new WebSocket('wss://api.talk.dev/v1/stream');

// Configure synthesis
ws.send(JSON.stringify({
  "action": "configure",
  "voice": "alex-conversational",
  "format": "webm"
}));

// Stream text for real-time synthesis
ws.send(JSON.stringify({
  "action": "synthesize",
  "text": "Hello, this is being synthesized in real-time!"
}));

// Receive audio chunks
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'audio_chunk') {
    playAudioChunk(data.audio_data);
  }
};

import { TalkAI } from '@talk/ai-sdk';

const client = new TalkAI('your-api-key');

// Basic synthesis
const audio = await client.synthesize({
  text: "Hello world",
  voice: "sarah-professional",
  format: "mp3"
});

// Voice cloning
const clone = await client.voices.clone({
  name: "My Custom Voice",
  audioFile: file,
  consentVerified: true
});

// Wait for completion
const voice = await client.voices.waitForClone(clone.clone_id);

// Use cloned voice
const customAudio = await client.synthesize({
  text: "Speaking with my cloned voice",
  voice: voice.voice_id
});

// Real-time streaming
const stream = client.createStream({
  voice: "alex-conversational",
  onAudioChunk: (chunk) => playAudio(chunk),
  onComplete: () => console.log('Stream finished')
});

stream.addText("This text will be synthesized in real-time");

from talkai import TalkAI

client = TalkAI(api_key="your-api-key")

# Basic synthesis
audio = client.synthesize(
    text="Hello world",
    voice="sarah-professional",
    format="mp3"
)

# Voice cloning
with open("sample.wav", "rb") as f:
    clone = client.voices.clone(
        name="My Custom Voice",
        audio_file=f,
        consent_verified=True
    )

# Use cloned voice
voice = client.voices.wait_for_clone(clone.clone_id)
custom_audio = client.synthesize(
    text="Speaking with my cloned voice",
    voice=voice.voice_id
)

X-RateLimit-Limit: 1000          # Requests per hour
X-RateLimit-Remaining: 856       # Remaining in window
X-RateLimit-Reset: 1642694400    # Reset timestamp

X-Usage-Characters: 1543         # Characters used this month
X-Usage-Minutes: 15.7           # Audio minutes generated
X-Usage-Cost: 3.14              # Cost in USD

{
  "error": "INVALID_VOICE",
  "message": "Voice 'invalid-voice-id' not found",
  "details": {
    "available_voices": ["sarah-professional", "alex-conversational"],
    "voice_categories": ["professional", "conversational", "storytelling"]
  },
  "request_id": "req_abc123def456"
}

GET /v1/health
{
  "status": "healthy",
  "version": "1.0.0",
  "regions": {
    "us-east-1": "healthy",
    "eu-west-1": "healthy",
    "ap-southeast-1": "healthy"
  },
  "response_time_p95": 89
}

// Webhook for voice clone completion
POST https://your-app.com/webhooks/voice-clone
{
  "event": "voice.clone.completed",
  "clone_id": "clone_abc123",
  "voice_id": "custom_voice_def456",
  "status": "completed",
  "timestamp": "2024-01-15T10:30:00Z"
}

// ElevenLabs format
const elevenlabs_request = {
  text: "Hello world",
  voice_settings: {
    stability: 0.5,
    similarity_boost: 0.8
  }
};

// talk.dev equivalent (simpler and more powerful)
const talkdev_request = {
  text: "Hello world",
  voice: "sarah-professional",
  emotion: "neutral",
  speed: 1.0
};