> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Voice Cloner API
> Clone any voice and generate realistic speech audio from text using custom voice samples.
## Overview
AI Voice Cloner creates realistic speech audio from text by cloning voices from sample audio files. The API analyzes the unique characteristics of a voice sample and produces high-quality voice synthesis with natural intonation, emotion, and speaking patterns that closely match the original voice.
The API accepts a voice sample and text. It has no language parameter.
## How It Works
1. **Upload voice sample** - Provide an audio file of the voice you want to clone
2. **Write the text** - Enter the text you want spoken in the cloned voice
3. **API clones and generates** - AI analyzes the voice and synthesizes speech
4. **Download the result** - Retrieve your audio file with the cloned voice
## Use Cases
* **Content creation** - Clone your own voice for consistent narration
* **Voice preservation** - Preserve voices of loved ones or historical figures
* **Multilingual content** - Create content in your voice across languages
* **Personalized assistants** - Custom voice for virtual assistants and chatbots
* **Accessibility** - Text-to-speech with your own voice
* **Entertainment** - Create audio content with specific voice characteristics
## Voice Sample Requirements
For best results, your voice sample should:
* **Be clear and high-quality** - Minimal background noise
* **Be at least 3 seconds long** - Longer clean samples can improve quality
* **Contain natural speech** - Conversational tone works best
* **Be single-speaker** - Only one person speaking in the sample
* **Have good enunciation** - Clear pronunciation of words
**Quality tip** - Use a quiet environment and a good microphone for recording your voice sample.
## Best Practices
### Voice Sample Guidelines
**Record naturally** - Speak in your natural tone and pace for the most authentic cloning.
* **Natural speech** - Read naturally, not robotically
* **Good audio quality** - Use proper recording equipment
* **Consistent volume** - Maintain steady speaking volume
* **No background noise** - Record in a quiet environment
* **Varied intonation** - Include different emotions and tones
### Text Guidelines
* **Natural punctuation** - Use periods, commas, and question marks for natural pauses
* **Avoid abbreviations** - Write out words fully (e.g., "Mister" not "Mr.")
* **Short sentences** - Break long text into shorter, digestible sentences
* **Read it aloud** - Test how text sounds before generating
### Optimizing Output Quality
| Technique | Why It Helps |
| :------------------ | :---------------------------------------- |
| High-quality sample | Better voice characteristics captured |
| Natural punctuation | Creates appropriate pauses and intonation |
| Phonetic spelling | Helps with unusual words or names |
| Sentence breaks | Improves rhythm and comprehension |
### Text Length Considerations
* **Short clips** - 1-2 sentences work great for social media
* **Medium content** - Paragraphs work well for narration
* **Long content** - Consider breaking into multiple clips for variety
## Code Examples
The Node.js examples create an audio project, then call `audioProjects.checkResult` to wait for completion and download the audio.
### Basic Voice Cloning
```python Python theme={null}
from magic_hour import Client
from os import getenv
client = Client(token=getenv("MAGIC_HOUR_API_KEY"))
result = client.v1.ai_voice_cloner.generate(
assets={
"audio_file_path": "path/to/voice_sample.mp3"
},
style={
"prompt": "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?"
},
name="Voice Cloner audio",
wait_for_completion=True,
download_outputs=True,
download_directory="."
)
if result.status == "complete":
print(f"✅ Voice cloning complete!")
print(f"Downloaded to: {result.downloaded_paths}")
print(f"Credits charged: {result.credits_charged}")
else:
print(f"❌ Job failed with status: {result.status}")
if result.error:
print(f"Error: {result.error.message}")
```
```javascript Node.js theme={null}
import { Client } from "magic-hour";
const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });
const project = await client.v1.aiVoiceCloner.create({
assets: {
audioFilePath: await client.v1.files.uploadFile("path/to/voice_sample.mp3"),
},
style: {
prompt: "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?",
},
name: "Voice Cloner audio",
});
const result = await client.v1.audioProjects.checkResult(
{ id: project.id },
{
waitForCompletion: true,
downloadOutputs: true,
downloadDirectory: ".",
}
);
console.log(`Status: ${result.status}`);
console.log(`Downloaded to: ${result.downloadedPaths}`);
```
### Clone Voice with URL
```python Python theme={null}
result = client.v1.ai_voice_cloner.generate(
assets={
"audio_file_path": "https://example.com/voice_sample.mp3"
},
style={
"prompt": "Welcome to the show! Today we're going to talk about something really exciting."
},
name="Voice Cloner audio",
wait_for_completion=True,
download_outputs=True,
download_directory="."
)
if result.status == "complete":
print(f"✅ Voice cloning complete!")
print(f"Downloaded to: {result.downloaded_paths}")
print(f"Credits charged: {result.credits_charged}")
else:
print(f"❌ Job failed with status: {result.status}")
if result.error:
print(f"Error: {result.error.message}")
```
```javascript Node.js theme={null}
const project = await client.v1.aiVoiceCloner.create({
assets: {
audioFilePath: await client.v1.files.uploadFile("https://example.com/voice_sample.mp3"),
},
style: {
prompt: "Welcome to the show! Today we're going to talk about something really exciting.",
},
name: "Voice Cloner audio",
});
const result = await client.v1.audioProjects.checkResult(
{ id: project.id },
{
waitForCompletion: true,
downloadOutputs: true,
downloadDirectory: ".",
}
);
console.log(`Downloaded to: ${result.downloadedPaths}`);
```
### Professional Narration
```python Python theme={null}
result = client.v1.ai_voice_cloner.generate(
assets={
"audio_file_path": "path/to/narrator_voice.mp3"
},
style={
"prompt": "In a world where technology meets creativity, Magic Hour brings your ideas to life."
},
name="Voice Cloner audio",
wait_for_completion=True,
download_outputs=True,
download_directory="."
)
if result.status == "complete":
print(f"✅ Voice cloning complete!")
print(f"Downloaded to: {result.downloaded_paths}")
print(f"Credits charged: {result.credits_charged}")
else:
print(f"❌ Job failed with status: {result.status}")
if result.error:
print(f"Error: {result.error.message}")
```
```javascript Node.js theme={null}
const project = await client.v1.aiVoiceCloner.create({
assets: {
audioFilePath: await client.v1.files.uploadFile("path/to/narrator_voice.mp3"),
},
style: {
prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.",
},
name: "Voice Cloner audio",
});
const result = await client.v1.audioProjects.checkResult(
{ id: project.id },
{
waitForCompletion: true,
downloadOutputs: true,
downloadDirectory: ".",
}
);
console.log(`Downloaded to: ${result.downloadedPaths}`);
```
### Combining with Lip Sync
Clone a voice, then sync it to a video:
```python Python theme={null}
from magic_hour import Client
from os import getenv
client = Client(token=getenv("MAGIC_HOUR_API_KEY"))
# Step 1: Clone the voice
voice_result = client.v1.ai_voice_cloner.generate(
assets={
"audio_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/you-are-just-a-line-of-code.mp3"
},
style={
"prompt": "This is my custom voiceover for the video."
},
name="Voice Cloner audio",
wait_for_completion=True,
download_outputs=True,
download_directory=".",
)
if voice_result.status != "complete" or not voice_result.downloaded_paths:
raise RuntimeError(f"Voice generation did not complete: {voice_result.status}")
# Step 2: Use the generated audio for lip sync
lip_sync_result = client.v1.lip_sync.generate(
assets={
"video_file_path": "https://raw.githubusercontent.com/runshouse/Sample_Assets/main/sideeyegirl.mp4",
"audio_file_path": voice_result.downloaded_paths[0], # local path now exists
"video_source": "file",
},
start_seconds=0,
end_seconds=2,
max_fps_limit=30,
style={"generation_mode": "lite"},
name="Lip Synced Video",
wait_for_completion=True,
download_outputs=True,
download_directory=".",
)
print("voice_status:", voice_result.status, "paths:", getattr(voice_result, "downloaded_paths", None))
print("lip_status:", lip_sync_result.status, "paths:", getattr(lip_sync_result, "downloaded_paths", None))
```
## API pricing
Voice cloning costs **0.1 credits per character** of generated text, rounded up to the nearest whole number. Inputs support up to 1,000 characters.
| Text Length | Credits |
| :----------------------------- | :---------- |
| 100 characters (1-2 sentences) | 10 credits |
| 500 characters (a paragraph) | 50 credits |
| 1,000 characters (maximum) | 100 credits |
**Try this in our Google Colab Cookbook:** [Run this API with sample
code](https://colab.research.google.com/drive/1NTHL_lr_s-qBJ-mSecSXPzRLi9_V5JiU?usp=sharing). Just
add your API key.
## API Reference
View full API specification
## Related Tools
Generate speech with celebrity and character voices
Sync generated audio with video lip movements
Create animated videos with audio