API 문서

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

The local API is included in the Pro and Studio plans. Create and manage your API keys from the API tab inside the app.

기본 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

Method	Path	Description	Scope
GET	`/api/voices`	List all voices	voices:read
GET	`/api/voices/{id}`	Get voice details	voices:read
PUT	`/api/voices/{id}`	Update voice metadata	voices:write
DELETE	`/api/voices/{id}`	Delete voice	voices:write
GET	`/api/favorites`	Get favorite voices	voices:read
POST	`/api/favorites/{id}`	Toggle favorite	voices:write

Text-to-Speech (TTS)

Method	Path	Description	Scope
POST	`/api/generate/clone`	Generate speech (cloned voice)	tts:generate
POST	`/api/generate/preset`	Generate speech (preset voice)	tts:generate
POST	`/api/generate/clone-chunked`	Chunked generation (per sentence)	tts:generate
POST	`/api/generate/clone-chunked-multivoice`	Multi-voice chunked generation	tts:generate
POST	`/api/generate/clone-chunked-multilang`	Multi-language chunked generation	tts:generate
POST	`/api/generate/regenerate-chunk`	Regenerate a single chunk	tts:generate
POST	`/api/generate/merge-chunks`	Merge chunks into final audio	tts:generate
POST	`/api/generation/cancel`	Cancel ongoing generation	tts:generate
POST	`/api/text/split`	Split text into sentences	audio:process

Voice Cloning & Design

Method	Path	Description	Scope
POST	`/api/clone/create-clips`	Create voice clone (multi-clip with regions)	clone:create
POST	`/api/clone/create`	Create voice clone (single sample)	clone:create
POST	`/api/clone/create-multi`	Create voice clone (multi-sample)	clone:create
POST	`/api/clone/cancel`	Cancel clone creation	clone:create
POST	`/api/design/create`	Create voice from description	clone:create
POST	`/api/design/cancel`	Cancel design creation	clone:create
POST	`/api/voices/{id}/generate-preview`	Generate voice preview	clone:create

Audio Processing

Method	Path	Description	Scope
POST	`/api/transcribe`	Transcribe audio (Whisper)	audio:process
POST	`/api/audio-duration`	Get audio file duration	audio:process
GET	`/api/audio/chunk/{task_id}/{index}`	Retrieve generated audio chunk	tts:generate
POST	`/api/download-video`	Download audio from video URL	audio:process

Timeline

Method	Path	Description	Scope
GET	`/api/timeline/{task_id}`	Get timeline layout	tts:timeline
POST	`/api/timeline/{task_id}/layout`	Save block positions	tts:timeline
POST	`/api/timeline/{task_id}/import-track`	Import external audio track	tts:timeline
POST	`/api/timeline/{task_id}/import-video`	Import video/image for timeline	tts:timeline
POST	`/api/generate/merge-timeline`	Merge timeline into single file	tts:timeline

System

Method	Path	Description	Scope
GET	`/api/system/stats`	CPU, RAM, GPU stats	system:read
GET	`/api/system/status`	Detailed system status	system:read
GET	`/api/system/gpu`	Detailed GPU information	system:read
GET	`/api/system/info`	Hardware info	system:read
GET	`/api/queue/status`	GPU queue status	system:read
POST	`/api/job/cancel`	Cancel a queued job	system:read
POST	`/api/api-keys`	Create API key	system:read
GET	`/api/api-keys`	List API keys	system:read
DELETE	`/api/api-keys/{key_id}`	Delete an API key	system:read
POST	`/api/api-keys/{key_id}/revoke`	Revoke an API key	system:read

WebSocket

Method	Path	Description	Scope
WS	`/ws`	Real-time progress updates	ws: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를 반환합니다. 기본 제한은 키별로 설정 가능합니다.

스코프

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

Scope	Description	Default limit/min
`tts:generate`	Generate speech (TTS)	10
`tts:timeline`	Timeline editor access	30
`voices:read`	Read voices	60
`voices:write`	Modify / delete voices	20
`clone:create`	Create voice clones	2
`audio:process`	Process audio files	5
`system:read`	Read system info	60
`ws:connect`	WebSocket connection	5