API 문서

ClonyVoice는 텍스트 음성 변환, 음성 복제, 오디오 처리를 애플리케이션에 통합할 수 있는 로컬 REST API를 제공합니다. ClonyVoice가 실행 중일 때 API가 작동합니다.

기본 URL

API는 로컬에서 다음 주소로 이용 가능합니다:

http://127.0.0.1:8765

인증

모든 API 요청에는 X-API-Key HTTP 헤더로 전달하는 API 키가 필요합니다. ClonyVoice 데스크톱 앱의 API 탭에서 키를 생성하세요.

X-API-Key: cvk_your_api_key_here

엔드포인트

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

코드 예제

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);

속도 제한

각 API 키에는 스코프별 속도 제한(분당 요청 수)이 있습니다. 초과 시 API가 HTTP 429를 반환합니다. 기본 제한은 키별로 설정 가능합니다.

스코프

각 엔드포인트에는 특정 스코프가 필요합니다. 키에는 기본적으로 모든 스코프가 부여됩니다.

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

법적 정보

개인정보 이용약관 쿠키 환불 음성 권리 법적 고지 쿠키 설정