Skip to main content
This documentation is for the legacy Python SDK. Please use the new Python SDK instead. See the migration guide for help upgrading.

​
Prerequisites

Sign up for a free Fish Audio account to get started with our API.
  1. Go to fish.audio/auth/signup
  2. Fill in your details to create an account, complete steps to verify your account.
  3. Log in to your account and navigate to the API section
Once you have an account, you’ll need an API key to authenticate your requests.
  1. Log in to your Fish Audio Dashboard
  2. Navigate to the API Keys section
  3. Click “Create New Key” and give it a descriptive name, set a expiration if desired
  4. Copy your key and store it securely
Keep your API key secret! Never commit it to version control or share it publicly.

​
Overview

Voice cloning allows you to generate speech that matches a specific voice using reference audio. Fish Audio supports two approaches:
  • Using pre-trained voice models (reference_id)
  • Providing reference audio directly in your request
Use reference_id when you’ll reuse a voice multiple times - it’s faster and more efficient. Use references for one-off voice cloning or testing different voices without creating models.

​
Using Reference Audio

Clone a voice by providing reference audio directly: 
from fish_audio_sdk import Session, TTSRequest, ReferenceAudio

session = Session("your_api_key")

# Load reference audio
with open("voice_sample.wav", "rb") as f:
    audio_data = f.read()

request = TTSRequest(
    text="This will sound like the reference voice",
    references=[
        ReferenceAudio(
            audio=audio_data,
            text="Text spoken in the reference audio"
        )
    ]
)

# Generate speech
with open("cloned_voice.mp3", "wb") as f:
    for chunk in session.tts(request):
        f.write(chunk)

​
Multiple References

Improve voice quality by providing multiple reference samples: 
references = []

# Add multiple voice samples
for i in range(3):
    with open(f"sample_{i}.wav", "rb") as f:
        references.append(ReferenceAudio(
            audio=f.read(),
            text=f"Text from sample {i}"
        ))

request = TTSRequest(
    text="Better voice quality with multiple references",
    references=references
)

​
Creating Voice Models

For repeated use, create a persistent voice model: 
# Create a voice model from samples
voices = []
texts = []

for i in range(3):
    with open(f"voice_{i}.wav", "rb") as f:
        voices.append(f.read())
        texts.append(f"Sample text {i}")

model = session.create_model(
    title="My Custom Voice",
    description="Voice cloned from samples",
    voices=voices,
    texts=texts,
    visibility="private"  # or "public", "unlist"
)

print(f"Created model: {model.id}")

# Use the model
request = TTSRequest(
    text="Using my saved voice model",
    reference_id=model.id
)

​
Best Practices

​
Audio Quality

For best results, reference audio should:
  • Be 10-30 seconds long per sample
  • Have clear speech without background noise
  • Match the language you’ll generate
  • Include varied intonation and emotion

​
Sample Text

The text parameter in ReferenceAudio should:
  • Match exactly what’s spoken in the audio
  • Include punctuation for proper prosody
  • Be in the same language as generation

​
Performance Tips

  1. Pre-upload models for frequently used voices
  2. Use 2-3 reference samples for optimal quality
  3. Keep samples under 30 seconds each
  4. Normalize audio levels before uploading

​
Audio Format Requirements

Supported formats for reference audio:
  • WAV (recommended)
  • MP3
  • M4A
  • Other common audio formats
Sample rates:
  • 16kHz minimum
  • 44.1kHz recommended
  • Mono or stereo (converted to mono)

​
Example: Voice Bank

Build a library of cloned voices: 
def create_voice_bank():
    voice_bank = {}

    # List existing models
    models = session.list_models(self_only=True)
    for model in models.items:
        voice_bank[model.title] = model.id

    return voice_bank

def generate_with_voice(text, voice_name):
    voice_bank = create_voice_bank()

    if voice_name not in voice_bank:
        print(f"Voice '{voice_name}' not found")
        return

    request = TTSRequest(
        text=text,
        reference_id=voice_bank[voice_name]
    )

    with open(f"{voice_name}_output.mp3", "wb") as f:
        for chunk in session.tts(request):
            f.write(chunk)

​
Combining with Emotions

Add emotions to cloned voices: 
request = TTSRequest(
    text="(happy) This is exciting news! (calm) Let me explain the details.",
    reference_id="your_model_id"
)

# Or with direct references
request = TTSRequest(
    text="(excited) Amazing discovery!",
    references=[reference_audio]
)

​
Error Handling

Common issues and solutions: 
try:
    request = TTSRequest(
        text="Test speech",
        references=[reference_audio]
    )

    for chunk in session.tts(request):
        # Process audio
        pass

except Exception as e:
    if "Invalid audio format" in str(e):
        print("Check audio format - use WAV or MP3")
    elif "Audio too short" in str(e):
        print("Reference audio should be at least 10 seconds")
    else:
        raise e