# Voice Creator Pro Desktop API

- **OpenAPI Version:** `3.2.0`
- **API Version:** `2.0.0`

HTTP API for voice cloning, voice design, text-to-speech, transcription, audiobooks, dubbing, clips and AI Cut.

## Base URL

The API runs on your computer at `http://127.0.0.1:8100`. Change the port in Settings or start the app with `--api-port`. Every route starts with `/api/v1/`, except the OpenAI-compatible `POST /v1/audio/speech`. Requests to an unknown path return the app's HTML page, not a 404.

## Authentication

No key is needed unless you set one in Settings or start the app with `--api-key`. Once set, send it as `X-API-Key: <key>`, `Authorization: Bearer <key>` or `?api_key=<key>`. `GET /api/v1/health` and `GET /api/v1/system/version` never need a key.

## Quick Start Workflow

1. **Check health**: `GET /api/v1/health`
2. **Pick a model**: `GET /api/v1/models` lists the models and what each supports
3. **Generate speech** using one of:
   - `POST /api/v1/tts/generate` to use a built-in speaker voice
   - `POST /api/v1/generation/clone` to clone a voice from reference audio or a saved voice
   - `POST /api/v1/generation/design` to create a voice from a text description
   - `POST /api/v1/conversion/convert` to convert existing speech to another voice
4. **Get audio**: Pass `?sync=true` to get audio in the response, or poll `GET /api/v1/generation/progress` then `GET /api/v1/generation/result`

The requested model loads automatically, so the first request after a model switch takes longer. `POST /api/v1/model/load` loads one ahead of time.

## Sync vs Async

All generation and transcription endpoints accept `?sync=true`. In sync mode, the request blocks until completion and returns the result directly. Generation has a hard 600s cap; transcription uses a 300s inactivity timeout (resets while progress events are flowing) so long audio can finish even if it takes longer than 5 minutes wall-clock. In async mode (default), the request returns immediately and you poll for progress/results.

## Streaming

For real-time audio streaming, use the `/stream` variants (e.g. `POST /api/v1/generation/clone/stream`). These return a `session_id`. Connect to `GET /api/v1/streaming/{session_id}/audio` to receive a chunked WAV stream as audio is generated. Call `POST /api/v1/streaming/{session_id}/finalize` when done to collect the complete audio as base64.

## Audio Format

All audio input/output uses base64-encoded WAV unless otherwise noted. The streaming audio endpoint returns raw WAV (PCM 16-bit mono). The output audio format can be changed via `PUT /api/v1/settings/audio-format`.

## Models

Multiple TTS models are available, each with different capabilities.
Query `GET /api/v1/models` to list all models, or `GET /api/v1/models/active`
for the current model's capabilities.

Models differ in:

- **Supported modes**: clone, design, and/or TTS (built-in speakers)
- **Languages**: varies by model and variant
- **Quality tiers**: each model has its own set of variants
- **Generation parameters**: model-specific tuning knobs (temperature, exaggeration, etc.)

Pass `model_family` on generation requests to target a specific model, or omit it
to use the currently configured model.

## Validation

All requests are validated against the target model's capabilities.
Invalid languages, quality tiers, or generation parameters return
a 400 error listing the valid options.

## Agents

`POST /api/v1/speak` speaks text out loud in a saved voice. `POST /v1/audio/speech` accepts OpenAI text-to-speech requests, so OpenAI clients work by pointing their base URL at this server. An MCP server for AI agents runs at `/mcp`.

## Live avatars

Connect a WebSocket to `/api/v1/talking-head/live` (pass the key as `?api_key=` when one is set) to get a talking face back in real time. Send JSON messages and audio, and receive video frames with their audio.

1. **Start**: `{"type": "start", "avatar_id": "av_..."}`, or `"stock_id"`, or `"image_base64"`. Optional: `"model"` (`lite` default, or `pro`), `"size"` (512, or 1024 with `pro`), `"idle"` (`loop` default, `live` or `none`), `"pace"` (`realtime` default, or `fast` to get frames as quickly as they render), `"framing"` (`face` default for a square close-up, or `photo` for the whole photo with the face blended back in, up to 1280 px on its long side; `ready` gives `width` and `height`) and `"voice"`, `"language"`, `"tts_model"` and `"tts_quality"` (a quality tier such as `higher_quality` or `faster`, the app setting if left out) as defaults for `say`. The voice model loads during start so the first `say` is quick. Send `"warm_tts": false` if you only send your own audio. The server answers with `loading` messages while models download and load, then `ready`.
2. **Speak**: `{"type": "say", "id": "m1", "text": "...", "voice": "Morgan", "language": "English"}` speaks in a saved voice. `tts_model` and `tts_quality` can also be set per `say`. Or send your own speech: `{"type": "audio_begin", "id": "a1", "sample_rate": 24000}`, then binary messages of 16-bit mono PCM, then `{"type": "audio_end"}`.
3. **Receive**: binary frames, plus `started` and `done` messages for each `id`. Each frame is a 20-byte little-endian header (`kind` u8 with 1 for speech and 2 for idle, `id_length` u8, reserved u16, `epoch` u32, `index` u32, `audio_offset` u32, `jpeg_length` u32), then the id, then a JPEG, then 40 ms of 16-bit mono PCM at the `sample_rate` from `ready`. Idle frames carry no audio.
4. **Control**: `{"type": "interrupt"}` stops the current speech and drops queued speech, `{"type": "clear"}` drops only the queue, and `{"type": "played", "samples": N, "epoch": E}` reports how many speech samples you have played in the current epoch. With `realtime` pace the server stays about one second ahead of what you report, or of the clock if you never report.

After an interrupt the server sends `interrupted` with a new `epoch`. Drop any frames with an older epoch. One live session runs at a time.

## Servers

- **URL:** `http://127.0.0.1:8100`
  - **Description:** Voice Creator Pro on this computer

## Sections

Each section lists its endpoints with parameters, request bodies and responses.

- [Health](https://voicecreator.pro/api-docs/desktop/health.md): Server health check and graceful shutdown.
- [System](https://voicecreator.pro/api-docs/desktop/system.md): Hardware info, GPU device selection, backend detection, and dev mode. Use `GET /api/v1/system/backend` to determine if CUDA/MLX/CPU is configured.
- [Setup](https://voicecreator.pro/api-docs/desktop/setup.md): First-run setup flow. Check `GET /api/v1/setup/status` to see if setup is required, then `GET /api/v1/setup/options` for available backends, `POST /api/v1/setup/start` to install, and `GET /api/v1/setup/progress` to poll.
- [Settings](https://voicecreator.pro/api-docs/desktop/settings.md): App configuration: VRAM mode, UI language, transcription model, speaker detection engine, audio output format, TTS model quality, generation mode, HTTP API and MCP settings. Most settings take effect immediately; some (model quality, low VRAM, generation mode) require a model reload.
- [Model](https://voicecreator.pro/api-docs/desktop/model.md): TTS model lifecycle. **You must load a model before generating speech.** Use `POST /api/v1/model/load` to load, `GET /api/v1/model/load/progress` to poll, and `GET /api/v1/model/status` to check what's loaded. The model auto-switches when you change generation mode or quality.
- [Generation](https://voicecreator.pro/api-docs/desktop/generation.md): Shared generation infrastructure: progress polling, result retrieval, cancellation, and queue status. These endpoints work across all generation modes (clone, design, TTS). Only one generation runs at a time.
- [Clone](https://voicecreator.pro/api-docs/desktop/clone.md): Voice cloning from reference audio. Provide 3-15 seconds of clear speech as `ref_audio_base64`, or reference a saved `voice_id`. Supports sync, async, and streaming modes.
- [Design](https://voicecreator.pro/api-docs/desktop/design.md): Voice creation from natural language descriptions. Describe the voice you want in `instruct_text`. Designed voices vary between calls — save via `POST /api/v1/voices` and use the saved design endpoints to reuse a voice.
- [TTS](https://voicecreator.pro/api-docs/desktop/tts.md): Text-to-speech with built-in speaker voices. List available speakers with `GET /api/v1/tts/speakers`, then generate with `POST /api/v1/tts/generate`. Supports optional `instruct` parameter for style control (e.g. 'speak slowly and softly').
- [Transcription](https://voicecreator.pro/api-docs/desktop/transcription.md): Speech-to-text (ASR). Supports sync and async modes, optional word-level timestamps, SRT subtitle output, and punctuation restoration from reference text. Only one transcription runs at a time.
- [Streaming](https://voicecreator.pro/api-docs/desktop/streaming.md): Real-time audio streaming sessions. After starting a stream via a `/stream` endpoint, use `GET /api/v1/streaming/{session_id}/audio` for chunked WAV playback, `GET /api/v1/streaming/{session_id}` for session status, and `POST /api/v1/streaming/{session_id}/finalize` to collect the complete audio. Sessions expire after 10 minutes.
- [Voices](https://voicecreator.pro/api-docs/desktop/voices.md): Saved voice library (CRUD). Voices are either cloned (from audio) or designed (from descriptions). Use the `voice_id` from saved voices in clone and design generation requests.
- [History](https://voicecreator.pro/api-docs/desktop/history.md): Generation history (CRUD). Stores past generation results with audio and metadata, newest first. Filterable by generation mode.
- [Cache](https://voicecreator.pro/api-docs/desktop/cache.md): Model and pip cache management. View cache sizes and clear caches to free disk space.
- [GPU Install](https://voicecreator.pro/api-docs/desktop/gpu-install.md): Legacy GPU acceleration installation. Prefer the Setup endpoints for new installations.
- [Conversion](https://voicecreator.pro/api-docs/desktop/conversion.md): Voice conversion. `POST /api/v1/conversion/convert` turns existing speech into a target voice. Poll `GET /api/v1/conversion/progress`, then collect `GET /api/v1/conversion/result`.
- [Audio](https://voicecreator.pro/api-docs/desktop/audio.md): Audio file format conversion.
- [Translation](https://voicecreator.pro/api-docs/desktop/translation.md): Text translation.
- [YouTube](https://voicecreator.pro/api-docs/desktop/youtube.md): Download audio from a YouTube link to use as reference audio, slice a range from it, or transcribe it.
- [Audiobook](https://voicecreator.pro/api-docs/desktop/audiobook.md): Audiobook projects. Import a script or document, assign voices to speakers, generate audio segment by segment or in batches, and combine or export the finished book. Each segment keeps every take in its history.
- [Dubbing](https://voicecreator.pro/api-docs/desktop/dubbing.md): Video dubbing projects. Transcribe a video, assign a voice to each speaker, generate the dubbed audio, and optionally run lip sync.
- [Clips](https://voicecreator.pro/api-docs/desktop/clips.md): Clips projects. Find short clips in a long video or YouTube link, reframe them, add captions and render them.
- [AI Cut](https://voicecreator.pro/api-docs/desktop/ai-cut.md): AI Cut projects. Analyse a recording against an optional script, cut retakes and filler, and render the result to MP4.
- [Subtitles](https://voicecreator.pro/api-docs/desktop/subtitles.md): Saved subtitle style presets.
- [Images](https://voicecreator.pro/api-docs/desktop/images.md): Generate images from a prompt with the image models on this computer.
- [Agent](https://voicecreator.pro/api-docs/desktop/agent.md): Speech for AI agents. Speak text in a saved voice, use the OpenAI-compatible speech endpoint, or follow speak events over SSE.
- [Avatars](https://voicecreator.pro/api-docs/desktop/avatars.md)
- [Uploads](https://voicecreator.pro/api-docs/desktop/uploads.md)

OpenAPI spec: https://voicecreator.pro/openapi-desktop.json