Generate speech from text using a voice profile.

Returns a GenerationResponse with status="generating" and an id to poll at voicebox_get_generation_status.

Speak text immediately — plays on the user's speakers.

Simpler than voicebox_generate: picks a profile automatically if not specified (falls back to per-client binding, then default).

Get the status of a speech generation job.

Poll this after voicebox_generate or voicebox_speak until status is "completed" or "failed".

Wait for a generation to complete, polling until done.

Cancel a running speech generation.

Regenerate speech with a new random seed.

Creates a new version of the generation with different voice characteristics.

Retry a failed generation with the same parameters.

Transcribe audio to text using Whisper STT.

Pass exactly one of audio_path (local file) or audio_base64 (base64-encoded audio bytes).

Generate text using Voicebox's built-in LLM.

Uses the Qwen3 model loaded in Voicebox (if any).

Compose text in a voice profile's character/personality.

Uses the profile's personality prompt to rewrite text in-character, suitable for feeding back into voicebox_generate.

Import an existing audio file as a generation in history.

Useful for bringing external audio into the Voicebox ecosystem for story editing, effects, or re-generation.

Stream speech audio directly and save to a file.

This bypasses the async generation queue and returns audio bytes in a single response. Good for short texts.

List all voice profiles (cloned voices and presets).

Returns a list of profile dicts with id, name, engine, and metadata. Use the returned id with voicebox_generate(profile_id=...).

Create a new custom voice profile.

After creating, add voice samples with voicebox_add_sample to enable voice cloning.

Get detailed information about a voice profile.

Includes profile settings, sample count, and metadata.

Update voice profile settings. Only provided fields are changed.

The Voicebox API requires the name field to be present in updates. If you don't provide a new name, the current name is fetched and preserved automatically.

Delete a voice profile and all its samples.

List preset voices available for a TTS engine.

Presets are pre-made voice profiles that don't require cloning.

Add a voice sample to a profile for voice cloning.

The sample should be a clean recording of the target voice. Multiple samples improve cloning quality.

List all voice samples for a profile.

Delete a voice sample from a profile.

Export a voice profile with all its samples and settings.

The exported data can be imported with voicebox_import_profile.

Import a voice profile from exported data.

Get the channels a voice profile is assigned to.

Assign a voice profile to specific channels.

Upload an avatar image for a voice profile.

Delete a voice profile's avatar image.

Update the default effects chain for a voice profile.

Update a voice sample's metadata. Only provided fields are changed.

Download a voice sample's audio and save it to a file.

List all stories.

Returns a list of story dicts with id, name, description, and item count.

Create a new story (audio project).

Stories are sequences of voice generations that can be arranged, trimmed, and exported as a single audio file.

Get a story with all its items, timings, and tracks.

Update story metadata. Only provided fields are changed.

Delete a story and all its items.

Add a generation to a story.

The generation's audio is placed at the specified time on the specified track.

Remove an item from a story.

Reorder items in a story.

Batch update start/end times for multiple story items at once.

Edit a story item — trim, split, move, set volume, or set version.

This is a combined tool for all item editing operations.

Export a complete story as an audio file.

Renders all items on all tracks into a single audio file.

Get status of all models — TTS, Whisper (STT), and LLM.

Returns a dict with a "models" list. Each model has:

• model_name: internal name

• display_name: human-readable name

• downloaded: whether it's on disk

• downloading: whether a download is in progress

• loaded: whether it's currently in VRAM

• size_mb: file size in MB

Load a model into VRAM for inference.

The model must be downloaded first (check with voicebox_list_models).

Unload a model from VRAM to free memory.

Download a model from HuggingFace to local cache.

Check progress with voicebox_get_download_progress.

Cancel an ongoing model download.

Get download progress for a model.

Delete a downloaded model from disk to free space.

Get the models cache directory path.

Migrate models to a new cache location.

Get progress of an ongoing model migration.

Note: This endpoint may be SSE (Server-Sent Events) streaming. If it hangs, the migration may still be running — check voicebox_get_active_tasks instead.

List all channels.

Channels are routing targets that map voice profiles to output destinations (speakers, apps, etc).

Create a new channel.

Update channel settings. Only provided fields are changed.

Delete a channel.

Get the voice profiles assigned to a channel.

Assign voice profiles to a channel.

List generation history with optional filters.

Get usage statistics — total generations, by profile, by engine.

Get details of a specific generation.

Includes text, profile, status, audio path, duration, seed, and versions.

Delete a generation from history.

Toggle the favorite status of a generation.

Export a generation's data (metadata + settings) as JSON.

Download a generation's audio and save it to a file.

List all versions of a generation (original + regenerations).

Set which version of a generation is the active/default one.

Delete a specific version of a generation.

Download a specific version's audio and save it to a file.

List all failed generations for retry or cleanup.

Note: This endpoint may return 404 if the Voicebox API routes /history/failed as /history/{generation_id}. This is a known Voicebox API routing issue.

Import history entries from exported data.

Export a generation's audio via the history export endpoint.

This may include processing (normalization, effects) unlike voicebox_save_audio which returns raw audio.

List all available audio effects (reverb, echo, EQ, etc).

Returns available effect types and their parameters.

List all saved effect presets.

Presets are reusable effect chains that can be applied to generations or profiles.

Create a new effect preset.

Get an effect preset by ID.

Update an effect preset. Only provided fields are changed.

Delete an effect preset.

Apply an effects chain to a generation, creating a new version.

Preview effects on a generation without creating a permanent version.

List recent captures (voice recordings with transcripts).

Get a capture with its transcript and metadata.

Delete a capture and its audio.

Download a capture's audio and save it to a file.

Refine a capture's transcript using an LLM for better accuracy.

Retranscribe a capture with a different Whisper model.

Check if the capture (recording) system is ready to use.

Returns whether a microphone is available and Whisper is loaded.

Get Voicebox health, GPU, and VRAM status.

Returns CPU/GPU memory usage, loaded models, and uptime. Use this to check if Voicebox is running and healthy.

Get filesystem health — disk usage, cache size, audio dir status.

Get global generation settings (defaults for all generations).

Update global generation settings. Only provided fields are changed.

Get capture (recording) settings.

Update capture settings. Only provided fields are changed.

Get all active background tasks (generations, downloads, etc).

Clear all completed/failed background tasks from the task list.

Clear temporary cache files (does not delete models or audio).

List all MCP client bindings.

Bindings map MCP clients (like Cursor) to default profiles and settings.

Create or update an MCP client binding.

Bindings let specific MCP clients (like Cursor) default to a specific voice profile.

Delete an MCP client binding.

Get CUDA backend status — whether GPU acceleration is available.

Get CUDA backend download progress (if installing CUDA support).