API Reference

Voice Cloning API

Clone voices from audio samples and generate text-to-speech audio. Supports multiple providers including ElevenLabs, Hume AI, and Chatterbox.

Providers

ElevenLabs

Industry-leading voice cloning with 30+ languages. Best overall quality.

Recommended

Hume AI (Octave)

Expressive voice with emotion control. Great for storytelling.

Chatterbox

Open-source alternative. English only, good for testing.

List Providers

GET/voice-clone/providers

Get available voice providers and their capabilities

bash

curl https://api.twin.actor/api/v1/voice-clone/providers \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

[
  {
    "id": "elevenlabs",
    "name": "ElevenLabs",
    "available": true,
    "languages": ["en", "es", "fr", "de", "it", "pt", "pl", "hi", "ar"],
    "features": ["cloning", "tts", "multilingual"]
  },
  {
    "id": "hume",
    "name": "Hume AI",
    "available": true,
    "languages": ["en"],
    "features": ["cloning", "tts", "emotion_control"]
  },
  {
    "id": "chatterbox",
    "name": "Chatterbox",
    "available": true,
    "languages": ["en"],
    "features": ["cloning", "tts"]
  }
]

Clone Voice

POST/voice-clone/clone

Clone a voice from an audio sample

Audio Requirements

Minimum 30 seconds of clear speech
Formats: MP3, WAV, M4A, WebM
Maximum file size: 50MB
Single speaker only

Request Body (multipart/form-data)

Name	Type	Description
`person_id`required	`integer`	Person to clone voice for
`provider`required	`string`	elevenlabs, hume, or chatterbox
`audio_file`required	`file`	Audio sample file

bash

curl -X POST https://api.twin.actor/api/v1/voice-clone/clone \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "person_id=1" \
  -F "provider=elevenlabs" \
  -F "audio_file=@voice_sample.mp3"

Response:

json

{
  "success": true,
  "status": "processing",
  "message": "Voice cloning started. Check person's has_voice field for completion.",
  "person_id": 1,
  "provider": "elevenlabs"
}

Voice cloning typically takes 1-2 minutes. Poll the person endpoint to check when has_voice becomes true.

200Cloning started

400Invalid audio file

403Insufficient credits (500 required)

404Person not found

Text-to-Speech

POST/voice-clone/tts

Generate speech audio from text using a cloned voice

Request Body

Name	Type	Description
`person_id`required	`integer`	Person with cloned voice
`text`required	`string`	Text to synthesize (max 5000 chars)
`provider`	`string`	Override default provider

bash

curl -X POST https://api.twin.actor/api/v1/voice-clone/tts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 1,
    "text": "Hello, this is a test of the text-to-speech system."
  }'

Response:

json

{
  "success": true,
  "audio_url": "https://storage.twin.actor/audio/tts_abc123.mp3",
  "duration_seconds": 3.5,
  "credits_used": 7
}

200Audio generated

400Text too long or empty

404Person not found or has no voice

Preview Voice

POST/voice-clone/preview

Generate a quick voice preview (no credits)

bash

curl -X POST https://api.twin.actor/api/v1/voice-clone/preview \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 1,
    "text": "This is a preview of my cloned voice."
  }'

Free Preview

Voice previews are free! Use them to test voice quality before generating longer audio.

Credit Costs

Operation	Cost
Voice cloning	500 credits
TTS audio	2 credits/second
Voice preview	FREE