Voice Engine API Overview

The Voice Engine powers PeachDesk Voice Studio — the text-to-speech, voice cloning, and audio editing workspace inside the PeachDesk dashboard. The same capabilities you use in the Studio UI (the Generation, Voices, Effects, Stories, Talk, Captures, and Settings tabs) are available programmatically through this REST API. Models run entirely on PeachDesk’s GPU infrastructure. You never download or manage model files — you simply pick an engine and voice, and PeachDesk serves the audio.

Base path

The PeachDesk API proxies the Voice Engine under the /api/voice base path. Every route below is relative to that prefix.

https://app.peachdeskai.com/api/voice

For example, generating speech is a POST to /api/voice/generate. Self-hosted deployments use the same path on their own host: https://your-peachdesk-instance/api/voice.

All Voice Engine routes are namespaced under /api/voice. A route documented on a resource page as POST /generate is reached at POST /api/voice/generate.

Authentication

Voice Engine requests authenticate with your PeachDesk API key — the same bibha_… key used everywhere else in this reference. Pass it in the X-API-Key header:

curl https://app.peachdeskai.com/api/voice/health \
  -H "X-API-Key: bibha_your_api_key"

An interactive session token in Authorization: Bearer … is also accepted — that is what the Voice Studio UI sends — but the API key is the credential for programmatic access. See Authentication. Requests are scoped to your organization, so voices, generations, stories, and captures are isolated per tenant. A missing or invalid credential returns 401; a valid credential without access to the requested resource returns 403.

Request and response conventions

Content type — JSON request bodies must be sent with Content-Type: application/json. Endpoints that accept uploads (voice samples, avatars, audio for transcription) use multipart/form-data.
Responses — Successful responses return the relevant JSON resource. Endpoints that return rendered audio respond with the audio bytes and an audio/wav (or similar) Content-Type.
IDs — Resource identifiers (generations, profiles, stories, captures) are UUID strings.

Errors

Errors use standard HTTP status codes. 4xx indicates a client problem (bad input, missing resource, unauthorized); 5xx indicates a server-side failure. The body is JSON with a detail field:

{
  "detail": "Profile not found"
}

Validation errors (422) return detail as a list describing each invalid field:

{
  "detail": [
    {
      "loc": ["body", "text"],
      "msg": "ensure this value has at least 1 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

Status	Meaning
`400 Bad Request`	Invalid parameters or an engine/voice combination that isn’t allowed
`401 Unauthorized`	Missing, invalid, expired, or archived credential
`402 Payment Required`	The organization is out of credits, or has hit its daily spend cap — generation, transcription and model serving all draw on the credit balance. See Errors
`403 Forbidden`	Authenticated but not permitted to access the resource
`404 Not Found`	The referenced resource (profile, generation, story, capture) does not exist
`422 Unprocessable Entity`	Request body failed validation
`5xx`	Generation, transcription, or model serving failed server-side

Resource groups

The Voice Engine API is organized into resource groups that mirror the Voice Studio tabs. Each page documents its full set of endpoints.

Generation

Synthesize speech from text, stream audio, warm up engines, retry, cancel, and check generation status.

Voices (Profiles)

Create and manage voice profiles — clone from audio or use a built-in voice — plus samples, avatars, and per-voice effects.

Effects

Preview and apply effects as versioned takes, and manage reusable effect presets.

Stories

Assemble multi-clip audio stories on a timeline: add, reorder, trim, split, and export items.

Talk (Conversation)

Drive real-time conversational voice sessions from the Talk tab.

Captures

Record, transcribe, refine, and manage voice captures.

Transcription

Transcribe uploaded audio to text.

History

List, favorite, export, and delete past generations.

Channels

Group voices into audio channels and manage channel membership.

Pronunciation

Define pronunciation rules that the engine applies before synthesis.

Audio

Fetch rendered audio for generations, versions, and voice samples.

Settings & Tasks

Read and update Voice Studio settings and inspect active background tasks.

The core endpoint: generate speech

Most integrations start with a single call. POST /api/voice/generate turns text into audio using one of your voice profiles. Generation runs asynchronously: the call returns immediately with a generation record in the generating state, then you poll status or fetch the audio when it completes. POST /api/voice/generate Generate speech from text using a voice profile.

string

required

ID of the voice profile to speak with. A profile is either Clone from audio or a Built-in voice (see the Voices page).

string

required

The text to synthesize. 1–50,000 characters. Long text is automatically split into chunks and stitched together.

string

default:"en"

ISO language code (for example en, es, fr, de, hi, ja, zh). Must be a language supported by the selected engine.

string

default:"vaani"

The TTS engine to use — one of the four served VAANI engines: vaani (VAANI), vaani-english (VAANI-ENGLISH), vaani-multilingual (VAANI-MULTILINGUAL), or vaani-indic (VAANI-INDIC). Any other value is rejected with 422. You select this from the engine dropdown in the Studio — no model download is required.

string

Legacy field. No served engine offers multiple sizes any more, so this is accepted and ignored. Omit it.

integer

Optional random seed for reproducible output. Omit for varied results across runs.

string

Legacy field: a natural-language delivery instruction, up to 500 characters. It is stored on the generation record but no served engine acts on it — the engine that offered instructed generation is no longer part of the catalog. To steer delivery, use audio_params instead.

boolean

default:"false"

When true and the profile has a personality prompt, the input text is rewritten in-character before synthesis.

array

Optional list of effect configs applied after generation, overriding the profile’s default effects chain. See Effects.

object

Two groups of knobs. Native ones are forwarded to the model — stability/similarity/style (or their direct equivalents temperature, cfg_weight, exaggeration), plus repetition_penalty, top_p, top_k, min_p, ref_vad_trim, and normalize_loudness. Each engine honors only the subset it advertises. Universal ones are applied to the rendered audio afterwards and work everywhere: speed, pitch, volume_db, sample_rate, and output_format. See Speech Generation for ranges.

boolean

default:"true"

Normalize the output audio volume.

integer

default:"800"

Maximum characters per chunk when splitting long text (100–5000).

integer

default:"50"

Crossfade duration in milliseconds between stitched chunks (0–500; use 0 for a hard cut).

Response

Returns a GenerationResponse. Because synthesis is asynchronous, status is typically generating on the initial response; poll GET /api/voice/generate/{generation_id}/status until it reads completed, then fetch the audio.

string

Unique generation ID. Use it to check status, fetch audio, retry, or cancel.

string

The voice profile used.

string

The text that was synthesized (after any personality rewrite).

string

Language code of the generation.

string

Engine used for synthesis.

string

Model size used, when applicable.

string

One of generating, completed, or failed.

number

Length of the rendered audio in seconds (populated once complete).

string

Failure reason when status is failed.

boolean

Whether the generation is marked as a favorite.

string

How the generation was created (for example manual or personality_speak).

string

ISO 8601 creation timestamp.

string

ID of the active effect take, if any.

curl -X POST https://app.peachdeskai.com/api/voice/generate \
  -H "X-API-Key: bibha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "8f1c2d3e-4b5a-6789-0abc-def123456789",
    "text": "Welcome to PeachDesk Voice Studio.",
    "language": "en",
    "engine": "vaani"
  }'

{
  "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "profile_id": "8f1c2d3e-4b5a-6789-0abc-def123456789",
  "text": "Welcome to PeachDesk Voice Studio.",
  "language": "en",
  "engine": "vaani",
  "model_size": null,
  "status": "generating",
  "duration": null,
  "is_favorited": false,
  "source": "manual",
  "created_at": "2026-06-23T10:35:00Z"
}

After the status reads completed, fetch the rendered bytes from GET /api/voice/audio/{generation_id} (see Audio). For a low-latency experience, stream synthesis directly with POST /api/voice/generate/stream (see Generation).

Health check

Confirm the Voice Engine is reachable and ready before issuing generation calls. GET /api/voice/health

curl https://app.peachdeskai.com/api/voice/health \
  -H "X-API-Key: bibha_your_api_key"

A healthy instance returns a JSON status payload. A degraded or unreachable engine returns a 5xx with a detail message.

Resources

Authentication & Errors

Voice Engine API

Bibha BRAHMA LLM

Bibha VAANI TTS

Bibha LIPI STT

Voice Engine API Overview

Base path

Authentication

Request and response conventions

Errors

Resource groups

Generation

Voices (Profiles)

Effects

Stories

Talk (Conversation)

Captures

Transcription

History

Channels

Pronunciation

Audio

Settings & Tasks

The core endpoint: generate speech

Response

Health check

​Base path

​Authentication

​Request and response conventions

​Errors

​Resource groups

Generation

Voices (Profiles)

Effects

Stories

Talk (Conversation)

Captures

Transcription

History

Channels

Pronunciation

Audio

Settings & Tasks

​The core endpoint: generate speech

​Response

​Health check

Base path

Authentication

Request and response conventions

Errors

Resource groups

The core endpoint: generate speech

Response

Health check