Documentación de la API

ClonyVoice proporciona una API REST local que te permite integrar texto a voz, clonación de voz y procesamiento de audio en tus propias aplicaciones. La API se ejecuta en tu máquina cada vez que ClonyVoice está abierto.

URL Base

La API está disponible localmente en:

http://127.0.0.1:8765

Autenticación

Todas las solicitudes a la API requieren una clave API enviada a través del encabezado HTTP X-API-Key. Crea claves en la aplicación de escritorio ClonyVoice en la pestaña 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

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

Limitación de Solicitudes

Cada clave API tiene límites por ámbito (solicitudes por minuto). Cuando se exceden, la API devuelve HTTP 429. Los límites predeterminados son configurables por clave.

Ámbitos

Cada endpoint requiere un ámbito específico. Las claves reciben todos los ámbitos por defecto.

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