API Documentation

ClonyVoice provides a local REST API that lets you integrate text-to-speech, voice cloning, and audio processing into your own applications. The API runs on your machine whenever ClonyVoice is open.

Base URL

The API is available locally at:

http://127.0.0.1:8765

Authentication

All API requests require an API key passed via the X-API-Key HTTP header. Create keys in the ClonyVoice desktop app under the API tab.

X-API-Key: cvk_your_api_key_here

Endpoints

Voices

MethodPathDescriptionScope
GET/api/voicesList all voicesvoices:read
GET/api/voices/{id}Get voice detailsvoices:read
PUT/api/voices/{id}Update voice metadatavoices:write
DELETE/api/voices/{id}Delete voicevoices:write
GET/api/categoriesList categoriesvoices:read
POST/api/categoriesCreate a categoryvoices:write
DELETE/api/categoriesDelete a categoryvoices:write
GET/api/favoritesGet favorite voicesvoices:read
POST/api/favorites/{id}Toggle favoritevoices:write
POST/api/voices/exportExport voices (.clonyvoice)voices:read
POST/api/voices/import/previewPreview import filevoices:write
POST/api/voices/importImport voicesvoices:write

Text-to-Speech (TTS)

MethodPathDescriptionScope
POST/api/generate/cloneGenerate speech (cloned voice)tts:generate
POST/api/generate/presetGenerate speech (preset voice)tts:generate
POST/api/generate/clone-chunkedChunked generation (per sentence)tts:generate
POST/api/generate/clone-chunked-multivoiceMulti-voice chunked generationtts:generate
POST/api/generate/clone-chunked-multilangMulti-language chunked generationtts:generate
POST/api/generate/regenerate-chunkRegenerate a single chunktts:generate
POST/api/generate/merge-chunksMerge chunks into final audiotts:generate
POST/api/generation/cancelCancel ongoing generationtts:generate
POST/api/text/splitSplit text into sentencesaudio:process

Voice Cloning & Design

MethodPathDescriptionScope
POST/api/clone/create-clipsCreate voice clone (multi-clip with regions)clone:create
POST/api/clone/createCreate voice clone (single sample)clone:create
POST/api/clone/create-multiCreate voice clone (multi-sample)clone:create
POST/api/clone/cancelCancel clone creationclone:create
POST/api/design/createCreate voice from descriptionclone:create
POST/api/design/cancelCancel design creationclone:create
POST/api/voices/{id}/generate-previewGenerate voice previewclone:create

Audio Processing

MethodPathDescriptionScope
POST/api/transcribeTranscribe audio (Whisper)audio:process
POST/api/translateTranslate text between languagesaudio:process
POST/api/audio-durationGet audio file durationaudio:process
GET/api/audio/chunk/{task_id}/{index}Retrieve generated audio chunktts:generate
POST/api/download-videoDownload audio from video URLaudio:process

Timeline

MethodPathDescriptionScope
GET/api/timeline/{task_id}Get timeline layouttts:timeline
POST/api/timeline/{task_id}/layoutSave block positionstts:timeline
POST/api/timeline/{task_id}/import-trackImport external audio tracktts:timeline
POST/api/timeline/{task_id}/import-videoImport video/image for timelinetts:timeline
POST/api/generate/merge-timelineMerge timeline into single filetts:timeline

Generations

MethodPathDescriptionScope
GET/api/generationsList generation historyvoices:read
GET/api/generations/{id}Get generation detailsvoices:read
DELETE/api/generations/{id}Delete a generationvoices:write

Montages

MethodPathDescriptionScope
GET/api/montagesList all montagesvoices:read
POST/api/montagesCreate a new montagevoices:write
GET/api/montages/{id}Get montage with generationsvoices:read
DELETE/api/montages/{id}Delete a montagevoices:write

System

MethodPathDescriptionScope
GET/api/system/statsCPU, RAM, GPU statssystem:read
GET/api/system/statusDetailed system statussystem:read
GET/api/system/gpuDetailed GPU informationsystem:read
GET/api/system/infoHardware infosystem:read
GET/api/queue/statusGPU queue statussystem:read
POST/api/job/cancelCancel a queued jobsystem:read
POST/api/api-keysCreate API keysystem:read
GET/api/api-keysList API keyssystem:read
DELETE/api/api-keys/{key_id}Delete an API keysystem:read
POST/api/api-keys/{key_id}/revokeRevoke an API keysystem:read

WebSocket

MethodPathDescriptionScope
WS/wsReal-time progress updatesws:connect

Code Examples

curl -X POST "http://127.0.0.1:8765/api/generate/clone" \ -H "X-API-Key: cvk_your_key" \ -H "Content-Type: application/json" \ -d '{ "voice_id": "voice_abc123", "text": "Hello, world!", "language": "en" }'
import requests response = requests.post( "http://127.0.0.1:8765/api/generate/clone", headers={"X-API-Key": "cvk_your_key"}, json={ "voice_id": "voice_abc123", "text": "Hello, world!", "language": "en" } ) print(response.json())
const response = await fetch( "http://127.0.0.1:8765/api/generate/clone", { method: "POST", headers: { "X-API-Key": "cvk_your_key", "Content-Type": "application/json" }, body: JSON.stringify({ voice_id: "voice_abc123", text: "Hello, world!", language: "en" }) } ); const data = await response.json(); console.log(data);

Rate Limiting

Each API key has per-scope rate limits (requests per minute). When exceeded, the API returns HTTP 429. The default limits are configurable per key.

Scopes

Each endpoint requires a specific scope. Keys are granted all scopes by default.

ScopeDescriptionDefault limit/min
tts:generateGenerate speech (TTS)10
tts:timelineTimeline editor access30
voices:readRead voices & categories60
voices:writeModify / delete voices20
clone:createCreate voice clones2
audio:processProcess audio files5
system:readRead system info60
ws:connectWebSocket connection5

Legal

Privacy Terms Cookies Refunds Voice Rights Legal Notices Cookie settings