Documentação API

ClonyVoice fornece uma API REST local que permite integrar text-to-speech, clonagem vocal e processamento de áudio em suas aplicações. A API roda na sua máquina sempre que o ClonyVoice está aberto.

URL Base

A API está disponível localmente em:

http://127.0.0.1:8765

Autenticação

Todas as requisições da API requerem uma chave API passada pelo header HTTP X-API-Key. Crie chaves no app desktop ClonyVoice na aba API.

X-API-Key: cvk_your_api_key_here

Endpoints

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

Exemplos de Código

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

Limites de Frequência

Cada chave API possui limites de frequência por escopo (requisições por minuto). Quando excedido, a API retorna HTTP 429. Os limites padrão são configuráveis por chave.

Escopos

Cada endpoint requer um escopo específico. As chaves recebem todos os escopos por padrão.

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