Complete reference for Lilith's audio APIs including Text-to-Speech (TTS), Speech-to-Text (STT), voice sessions, voice cloning, and audio quality assurance.
Text-to-Speech (TTS)#
Synthesize Speech#
POST /v1/tts:synthesize
POST /v1/tts/synthesize
Convert text to speech with customizable voice and SSML support.
Request Body:
{
"text": "Hello, welcome to meditation.",
"voice_id": "zen-master-01",
"format": "opus",
"ssml": "<speak><prosody rate='slow'>Hello</prosody></speak>",
"stream": false,
"language": "en-US",
"style_tokens": ["calm", "soothing"]
}
Response:
{
"synthesis_id": "syn_abc123",
"audio_url": "https://cdn.lilith.app/audio/syn_abc123.opus",
"duration_ms": 2500,
"format": "opus",
"sample_rate": 48000
}
Stream TTS#
POST /v1/tts/synthesize/stream
Stream synthesized audio in real-time for low-latency applications.
Response: audio/opus stream with chunked transfer encoding
Async TTS Job#
POST /v1/tts/synthesize/async
Queue long-form content for background synthesis.
Request Body:
{
"text": "Long meditation script...",
"voice_id": "guide-01",
"callback_url": "https://your-app.com/webhook"
}
Response:
{
"job_id": "job_xyz789",
"status": "queued",
"estimated_completion": "2026-01-03T12:00:00Z"
}
TTS Job Management#
GET /v1/tts/jobs
GET /v1/tts/jobs/{jobId}
GET /v1/tts/jobs/{jobId}/audio
DELETE /v1/tts/jobs/{jobId}
Voice Management#
List Voices#
GET /v1/voices
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | language | string | Filter by language
(BCP-47) | | gender | string | male, female, neutral | | style |
string | calm, authoritative, soothing | | limit | number | Max results
(default: 50) |
Response:
{
"voices": [
{
"voice_id": "zen-master-01",
"name": "Zen Master Takeshi",
"language": "en-US",
"gender": "male",
"style": ["calm", "wise"],
"preview_url": "https://cdn.lilith.app/voices/preview/zen-master-01.mp3"
}
],
"total": 100
}
Get Voice Details#
GET /v1/voices/{voiceId}
Voice Preview#
GET /v1/voices/{voiceId}/preview
Returns a sample audio clip demonstrating the voice.
Voice Lexicons#
Custom pronunciation dictionaries per voice.
GET /v1/voices/{voiceId}/lexicons
POST /v1/voices/{voiceId}/lexicons
PATCH /v1/voices/{voiceId}/lexicons/{lexiconId}
DELETE /v1/voices/{voiceId}/lexicons/{lexiconId}
Lexicon Entry:
{
"word": "Dhyana",
"phoneme": "ˈdjɑːnə",
"alias": "dhya-na"
}
Voice Cloning#
Consent Management#
POST /v1/voice-cloning/consent
GET /v1/voice-cloning/consent/{userId}
Voice cloning requires explicit user consent with legal acknowledgment.
Consent Request:
{
"user_id": "user_123",
"scope": ["personal_use", "meditation_guides"],
"duration_days": 365,
"acknowledgment": "I consent to voice cloning..."
}
Clone Voice#
POST /v1/voices/clone
POST /v1/voice-cloning/initiate
Request: multipart/form-data
audio_sample: Audio file (min 10s, WAV/MP3/FLAC)consent_token: Consent verification tokenvoice_name: Custom name for the cloned voice
Cloning Workflows#
POST /v1/voice-cloning/workflows
GET /v1/voice-cloning/workflows/{workflowId}
GET /v1/voice-cloning/workflows/{workflowId}/progress
POST /v1/voice-cloning/workflows/{workflowId}/approve
Workflow States:
pending_consent- Awaiting consent verificationprocessing- Audio analysis in progressreview- Ready for quality reviewapproved- Voice available for userejected- Failed quality checks
List Voice Clones#
GET /v1/voice-clones
Voice Library#
Search Voices#
GET /v1/voice-library/search
Query Parameters: | Parameter | Type | Description |
|-----------|------|-------------| | q | string | Search query | | category
| string | Category filter | | tags | string[] | Tag filters | |
style_tokens | string[] | Style filters |
Categories & Tags#
GET /v1/voice-library/categories
GET /v1/voice-library/tags
GET /v1/voice-library/style-tokens
Collections#
GET /v1/voice-library/collections
POST /v1/voice-library/collections
Voice Reviews#
POST /v1/voice-library/voices/{voiceId}/reviews
GET /v1/voice-library/voices/{voiceId}/reviews
Analytics#
GET /v1/voice-library/analytics/usage
Speech-to-Text (STT)#
Transcribe Audio#
POST /v1/stt/transcribe
Request: multipart/form-data
audio: Audio file (WAV, MP3, FLAC, OGG)language: Language code (optional, auto-detect)model: Model selection (whisper-large,whisper-medium)
Response:
{
"transcription_id": "tr_abc123",
"text": "Hello, this is a meditation...",
"language": "en",
"confidence": 0.95,
"words": [{ "word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.98 }],
"duration_ms": 5000
}
Streaming Transcription#
POST /v1/stt/transcribe/stream
WebSocket endpoint for real-time transcription with partial hypotheses.
WebSocket Events:
partial- Interim transcriptionfinal- Completed segmentend- Stream complete
Available Models#
GET /v1/stt/models
Real-Time Voice Sessions#
Session Management#
POST /v1/voice/sessions
GET /v1/voice/sessions/{sessionId}
POST /v1/voice/sessions/{sessionId}/start
DELETE /v1/voice/sessions/{sessionId}
Create Session:
{
"persona_id": "zen-master",
"voice_id": "zen-master-01",
"mode": "duplex",
"vad_enabled": true,
"barge_in_enabled": true
}
Audio Input/Output#
POST /v1/voice/sessions/{sessionId}/audio-input
GET /v1/voice/sessions/{sessionId}/audio
POST /v1/voice/sessions/{sessionId}/process-text
GET /v1/voice/sessions/{sessionId}/stream-tts
Push-to-Talk#
POST /v1/voice/sessions/{sessionId}/push-to-talk/start
POST /v1/voice/sessions/{sessionId}/push-to-talk/stop
Voice Activity Detection (VAD)#
POST /v1/voice/sessions/{sessionId}/vad/activity
POST /v1/voice/sessions/{sessionId}/vad/silence
POST /v1/voice/vad/configure
Barge-In (Interruption)#
POST /v1/voice/sessions/{sessionId}/start-ai-response
POST /v1/voice/sessions/{sessionId}/barge-in
Diagnostics#
GET /v1/voice/sessions/{sessionId}/diagnostics
GET /v1/voice/sessions/{sessionId}/diagnostics/detailed
Audio Quality Assurance#
MOS (Mean Opinion Score)#
POST /v1/audio/qa/mos/calculate
POST /v1/audio/qa/mos/panel/create
POST /v1/audio/qa/mos/panel/{panelId}/evaluate
GET /v1/audio/qa/mos/panel/{panelId}/results
Audio Analysis#
POST /v1/audio/qa/clipping/analyze
POST /v1/audio/qa/artifacts/detect
POST /v1/audio/qa/snr/analyze
POST /v1/audio/qa/frequency/analyze
LUFS Normalization#
POST /v1/audio/qa/lufs/measure
POST /v1/audio/qa/lufs/validate
POST /v1/audio/qa/lufs/normalize
POST /v1/audio/qa/lufs/batch-process
GET /v1/audio/qa/lufs/batch/{jobId}/status
Target: -16 LUFS for consistent loudness
Quality Reports#
POST /v1/audio/qa/metrics/analyze
POST /v1/audio/qa/compare
POST /v1/audio/qa/reports/generate
Real-Time Monitoring#
POST /v1/audio/qa/monitor/start
GET /v1/audio/qa/monitor/{sessionId}/alerts
POST /v1/audio/qa/monitor/{sessionId}/stop
Standards Configuration#
POST /v1/audio/qa/standards/configure
POST /v1/audio/qa/validate
Voice Pipeline#
Configuration#
GET /v1/voice/pipeline/config
POST /v1/voice/pipeline/config
GET /v1/voice/pipeline/health
GET /v1/voice/pipeline/audio-config
GET /v1/voice/pipeline/metrics
Circuit Breakers#
GET /v1/voice/pipeline/circuit-breakers
POST /v1/voice/pipeline/reset-overload
Optimization#
POST /v1/voice/pipeline/optimize
POST /v1/voice/pipeline/priority-test
HLS Streaming#
For lecture and meditation audio delivery:
GET /v1/tts/hls/{synthesisId}/manifest.m3u8
GET /v1/tts/hls/{synthesisId}/playlist.m3u8
GET /v1/tts/hls/{synthesisId}/segments/{segmentFile}
Usage & Billing#
User Usage#
GET /v1/tts/usage/{userId}
GET /v1/tts/usage/{userId}/stats
Token Management#
POST /v1/tts/usage/tokens/initialize
POST /v1/tts/usage/tokens/topup
Consent History#
GET /v1/tts/consent/{userId}/history
POST /v1/tts/consent/grant
POST /v1/tts/consent/revoke
Watermarking & Abuse Prevention#
Watermark Detection#
GET /v1/tts/watermarks/{watermarkId}
POST /v1/tts/watermarks/detect
Abuse Metrics#
GET /v1/tts/abuse/metrics/{userId}
Audio Handoff#
For cross-device audio session transfer:
WS /v1/audio-handoff/websocket
Enables seamless audio handoff between devices during meditation sessions.
Error Codes#
| Code | Description |
|---|---|
audio.invalid_format |
Unsupported audio format |
tts.voice_not_found |
Voice ID not found |
tts.consent_required |
Voice cloning requires consent |
tts.rate_limited |
TTS quota exceeded |
stt.transcription_failed |
STT processing error |
voice.session_expired |
Voice session timed out |
Rate Limits#
| Endpoint | Limit |
|---|---|
| TTS Synthesis | 100 req/min |
| STT Transcription | 50 req/min |
| Voice Sessions | 10 concurrent |
| Voice Cloning | 5 req/day |