Voice
Voice generation via ElevenLabs. Each creature has its own voice settings in its definition file.
GET /api/v1/voice/list-available — List all voices available from ElevenLabs.
GET /api/v1/voice/subscription — Get the current ElevenLabs API subscription status (remaining characters, tier, etc.).
POST /api/v1/voice — Generate a sound file of a creature speaking the given text, using that creature’s own ElevenLabs voice settings. Long text can outlive the 60-second HTTP timeout, so this runs as an async job: it returns 202 with a job_id, then publishes progress and completion over the WebSocket job-progress / job-complete streams (keyed by the job_id) — or poll GET /api/v1/job/{job_id}. An optional title is stored in the sound file’s metadata.
{
"creature_id": "uuid",
"text": "Polly wants a cracker!",
"title": "optional, metadata only"
}Speech-to-Text
Transcription powered by whisper.cpp. The Creature Listener uses this to offload transcription from the Pi 5 to the server.
POST /api/v1/stt/transcribe — Transcribe raw audio to text. Accepts 16kHz mono float32 PCM audio as a raw binary request body.
// Response
{
"status": "ok",
"transcript": "Hey Beaky, what's for dinner?",
"audio_duration_sec": 2.5,
"transcription_time_ms": 340
}