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

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	voices:write
DELETE	`/api/voices/{id}`	Delete voice	voices:write
GET	`/api/favorites`	Get favorites	voices:read
POST	`/api/favorites/{id}`	Toggle favorite	voices:write

Text-to-Speech (TTS)

Method	Path	Description	Scope
POST	`/api/generate/clone`	Generate speech (clone)	tts:generate
POST	`/api/generate/preset`	Generate speech (preset)	tts:generate
POST	`/api/generate/design`	Generate speech (design)	tts:generate
POST	`/api/text/split`	Split text into sentences	audio:process
POST	`/api/generation/cancel`	Cancel generation	tts:generate

Voice Cloning & Design

Method	Path	Description	Scope
POST	`/api/clone/create`	Create voice clone	clone:create
POST	`/api/clone/create-multi`	Multi-sample clone	clone:create
POST	`/api/design/create`	Create voice from description	clone:create

Audio Processing

Method	Path	Description	Scope
POST	`/api/transcribe`	Transcribe audio (Whisper)	audio:process
POST	`/api/audio-duration`	Get audio duration	audio:process

System

Method	Path	Description	Scope
GET	`/api/system/stats`	CPU, RAM, GPU stats	system:read
GET	`/api/system/info`	Hardware info	system:read
GET	`/api/api-keys`	List API keys	system:read
POST	`/api/api-keys`	Create 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 & categories	60
`voices:write`	Modify / delete voices	20
`clone:create`	Create voice clones	2
`audio:process`	Process audio files	5
`projects:read`	Read compositions	60
`projects:write`	Modify compositions	20
`system:read`	Read system info	60
`ws:connect`	WebSocket connection	5