GPT-SoVITS User Guide

GPT-SoVITS is an open-source few-shot voice cloning and text-to-speech system. Hand it a 3--10 second audio clip of any voice along with its transcript, and it synthesizes new speech that sounds like that person. Fine-tune on about one minute of audio for even higher fidelity. The toolkit supports Chinese (Mandarin and Cantonese), English, Japanese, and Korean, with automatic language detection and cross-lingual synthesis.

Six model generations are available -- v1, v2, v3, v4, v2Pro, and v2ProPlus -- each improving audio quality, language coverage, or speaker similarity. Every generation ships with pretrained weights so you can start generating speech immediately, and every generation can be fine-tuned on your own voice data through the built-in training pipeline.

1. Quick Start

This section gets you from zero to synthesized speech in the shortest path possible. Detailed explanations follow in later sections.

Prerequisites: Python 3.11+, an NVIDIA GPU with CUDA 12.6 or 12.8, and ffmpeg installed on your PATH.

# 1. Clone the repository
git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS

# 2. Install dependencies
pip install -r requirements.txt

# 3. Launch the main WebUI
python webui.py

The WebUI opens at http://localhost:9874. Navigate to the inference tab, load pretrained model weights, upload a 3--10 second reference clip, type the transcript of that clip, then type new text and click synthesize.

Tip

For the fastest results without any training, use the v2 pretrained models (the default). Record yourself reading a single sentence clearly, upload it as the reference audio, and type that sentence as the reference text. Then type whatever you want synthesized in the target text box.

If you want to skip the WebUI entirely, the command-line interface works in one shot:

python GPT_SoVITS/inference_cli.py \
  --ref_audio "my_reference.wav" \
  --ref_text "Hello, this is my reference sentence." \
  --ref_language "en" \
  --target_text "This is the text I want spoken in my voice." \
  --target_language "en" \
  --output_path "output.wav"

2. Installation

2.1 System Requirements

Important

ffmpeg must be installed and available on your system PATH. On Ubuntu: sudo apt install ffmpeg. On Windows: download from ffmpeg.org and add the bin folder to PATH. Without it, audio loading and conversion will fail silently or throw errors.

Warning

AMD GPUs with ROCm have limited support. GPU detection issues have been reported with ROCm 7.2 on Windows (see GitHub issue #2743). If you need AMD support, Linux with ROCm 6.x is more reliable.

2.2 Windows Installation

The repository includes a PowerShell install script that handles dependencies and model downloads:

# Standard CUDA 12.6 install, models from HuggingFace
.\install.ps1 -Device CU126 -Source HF

# CUDA 12.8, models from ModelScope (faster in China)
.\install.ps1 -Device CU128 -Source ModelScope

# CPU-only (no GPU acceleration)
.\install.ps1 -Device CPU -Source HF

Warning

If install.ps1 fails to execute, check your PowerShell execution policy: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned. Some users have reported the script not working on certain Windows configurations (#2757) -- in that case, fall back to the manual pip install method below.

2.3 Linux Installation

git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS
bash install.sh

Or install manually:

pip install -r requirements.txt

2.4 Docker Installation

# Build with CUDA 12.6
bash docker_build.sh --cuda 12.6

# Build with CUDA 12.8
bash docker_build.sh --cuda 12.8

# Lite build (smaller image, inference only)
bash docker_build.sh --cuda 12.6 --lite

A docker-compose.yaml is included for orchestrated deployment:

docker compose up -d

2.5 Manual Dependency Installation

If the automated scripts fail, install manually:

pip install -r requirements.txt

Ensure cmake is available (needed to build some native extensions):

# Ubuntu/Debian
sudo apt install cmake

# Windows (via winget)
winget install cmake

2.6 Pretrained Models

Pretrained models must be placed in GPT_SoVITS/pretrained_models/. The install scripts download them automatically. If you need to download manually:

Download from HuggingFace or ModelScope and place them in the appropriate subdirectories under GPT_SoVITS/pretrained_models/.

Additionally, the G2PW phoneme model (used for Chinese G2P) belongs in GPT_SoVITS/text/G2PWModel/.

3. Configuration

3.1 Inference Configuration File

The primary configuration file for inference is:

GPT_SoVITS/configs/tts_infer.yaml

This YAML file controls which model weights to load, device placement, and precision. Each model version has its own section. Key settings:

# Example structure (per version)
device: cuda        # "cuda" or "cpu"
is_half: true       # Half precision (FP16) — faster, less VRAM
version: v2         # v1, v2, v3, v4, v2Pro, v2ProPlus
t2s_weights_path: GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt
vits_weights_path: GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth
bert_base_path: GPT_SoVITS/pretrained_models/chinese-roberta-wwm-ext-large
cnhuhbert_base_path: GPT_SoVITS/pretrained_models/chinese-hubert-base

3.2 Environment Variables

These environment variables control global behavior (set them before launching):

3.3 Port Configuration

All ports are configured in GPT_SoVITS/config.py:

3.4 Precision and Device Settings

Half precision (FP16) is the default and runs faster with less VRAM. If you encounter NaN outputs or distorted audio on older GPUs, disable it:

# Via environment variable
export is_half=False
python webui.py

Or edit tts_infer.yaml and set is_half: false.

3.5 UI Language

The interface supports 13 locales: en_US, zh_CN, zh_TW, ja_JP, ko_KR, and more. The default is auto-detected from your system locale. To force a specific language, set the language environment variable:

export language=en_US
python webui.py

4. Core Usage

4.1 The Main WebUI

Launch with:

python webui.py

This opens the full Gradio interface at http://localhost:9874 with tabs for both training and inference. The WebUI is the recommended way to interact with GPT-SoVITS for most users.

Note

The WebUI is a Gradio application. It works in any modern browser. If you set is_share=True, Gradio generates a public URL you can share with others temporarily.

4.2 Inference GUI (Desktop)

For a dedicated inference-only experience, GPT-SoVITS includes a Qt-based desktop GUI:

python GPT_SoVITS/inference_gui.py

This is a standalone window application that focuses purely on text-to-speech synthesis without the training features.

4.3 Inference CLI

For scripting and automation, use the command-line interface:

python GPT_SoVITS/inference_cli.py \
  --gpt_model "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt" \
  --sovits_model "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth" \
  --ref_audio "reference.wav" \
  --ref_text "This is the reference transcript." \
  --ref_language "en" \
  --target_text "Generate this new sentence in the cloned voice." \
  --target_language "en" \
  --output_path "output.wav"

4.4 API v2 (Recommended)

API v2 is the recommended programmatic interface. It reads its initial configuration from GPT_SoVITS/configs/tts_infer.yaml, so you can pre-configure model paths rather than passing them on every request.

Start the API server:

python api_v2.py
# Default: binds to 127.0.0.1:9880

# Custom bind address and port
python api_v2.py -a 0.0.0.0 -p 8080

# Custom config file
python api_v2.py -c my_custom_config.yaml

Tip

API v2 binds to 127.0.0.1 by default (localhost only). To expose it on your network, use -a 0.0.0.0. API v1 binds to 0.0.0.0 by default -- be aware of this security difference.

Endpoints:

TTS request (POST):

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test of voice cloning.",
    "text_lang": "en",
    "ref_audio_path": "/path/to/reference.wav",
    "prompt_text": "This is the reference transcript.",
    "prompt_lang": "en",
    "media_type": "wav"
  }' \
  --output output.wav

TTS request (GET):

curl "http://localhost:9880/tts?text=Hello+world&text_lang=en&ref_audio_path=/path/to/ref.wav&prompt_text=Reference+transcript&prompt_lang=en" \
  --output output.wav

Full parameter reference:

Note

The prompt_text parameter is required for v3 models. Omitting it triggers an error. For v1/v2/v4, it is optional but recommended for better quality.

Switching models at runtime:

# Switch GPT weights
curl "http://localhost:9880/set_gpt_weights?weights_path=/path/to/new_gpt.ckpt"

# Switch SoVITS weights
curl "http://localhost:9880/set_sovits_weights?weights_path=/path/to/new_sovits.pth"

# Set new reference audio
curl "http://localhost:9880/set_refer_audio?refer_audio_path=/path/to/new_ref.wav"

4.5 API v1 (Legacy)

API v1 is the older interface, still functional but API v2 is preferred for new projects.

python api.py \
  -g "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s1bert25hz-5kh-longer-epoch=12-step=369668.ckpt" \
  -s "GPT_SoVITS/pretrained_models/gsv-v2final-pretrained/s2G2333k.pth" \
  -dr "reference.wav" \
  -dt "This is the reference transcript." \
  -dl "en"

Endpoints:

Example TTS request:

curl -X POST "http://localhost:9880/" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is synthesized speech.",
    "text_language": "en"
  }' \
  --output output.wav

4.6 Language Codes

Tip

Use auto for mixed-language text. The system detects language boundaries automatically and applies the appropriate G2P (grapheme-to-phoneme) processing per segment. Use all_* codes only when you know the entire input is a single language -- this disables detection and can produce cleaner phoneme sequences.

4.7 Streaming Modes

Streaming delivers audio chunks as they are generated rather than waiting for the full output. This reduces time-to-first-audio for long texts.

API v2 streaming modes:

API v1 streaming modes (via -sm flag or request param):

Caution

SoVITS v3 and v4 models do not support streaming inference. Attempting to use streaming with v3/v4 raises a RuntimeError. Use v1, v2, v2Pro, or v2ProPlus if you need streaming.

5. Common Tasks

5.1 Zero-Shot Voice Cloning (No Training)

The simplest workflow: clone a voice using only a short reference clip.

1. Prepare a clean audio clip of the target voice, 3 to 10 seconds long.
2. Transcribe the clip exactly.
3. Choose your interface (WebUI, CLI, or API) and synthesize.

Via CLI:

python GPT_SoVITS/inference_cli.py \
  --ref_audio "speaker_sample.wav" \
  --ref_text "Good morning, welcome to our presentation." \
  --ref_language "en" \
  --target_text "Thank you for joining us today. We have exciting news to share." \
  --target_language "en" \
  --output_path "cloned_output.wav"

Via API v2:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thank you for joining us today.",
    "text_lang": "en",
    "ref_audio_path": "speaker_sample.wav",
    "prompt_text": "Good morning, welcome to our presentation.",
    "prompt_lang": "en"
  }' \
  --output cloned_output.wav

Tip

For best zero-shot results: use a clean recording with no background noise, speak naturally at a moderate pace, and ensure the reference clip is between 5 and 10 seconds. Clips shorter than 3 seconds or longer than 10 seconds are rejected by the system.

5.2 Fine-Tuning a Voice (Few-Shot Training)

For higher-quality voice cloning, fine-tune on approximately one minute of target voice audio. The full training pipeline runs through the WebUI at http://localhost:9874.

Step 1: Prepare Audio Data

Collect clean recordings of the target speaker. For best results:

• Record in a quiet environment
• Use consistent microphone placement
• Aim for 1--5 minutes of clear speech

Step 2: Slice Audio

Use the built-in audio slicer to split long recordings into manageable segments:

python tools/slice_audio.py --input raw_audio/ --output sliced_audio/

Or use the slicer tab in the WebUI.

Step 3: Vocal Separation (Optional)

If your recordings have background music or noise, separate vocals using UVR5:

python tools/uvr5/webui.py

This launches the UVR5 interface at http://localhost:9873. It supports BS-RoFormer, MDXNet, and VR separation models.

Step 4: ASR Annotation

Generate transcripts automatically:

# Using Faster Whisper (multilingual)
python tools/asr/fasterwhisper_asr.py --input sliced_audio/ --output annotations/

# Using FunASR (Chinese/Cantonese)
python tools/asr/funasr_asr.py --input sliced_audio/ --output annotations/

Step 5: Review and Fix Annotations

Launch the subtitle fix tool to manually correct ASR errors:

python tools/subfix_webui.py

This opens at http://localhost:9871. Accurate transcripts directly improve synthesis quality.

Step 6: Run Training Pipeline via WebUI

In the WebUI training tab, the pipeline runs these stages in sequence:

1. Text extraction (1-get-text.py) -- extracts phoneme sequences
2. HuBERT feature extraction (2-get-hubert-wav32k.py) -- extracts acoustic features
3. Speaker verification extraction (2-get-sv.py) -- only for v2Pro/v2ProPlus models
4. Semantic token extraction (3-get-semantic.py) -- converts to semantic tokens
5. GPT training (s1_train.py) -- trains the autoregressive model
6. SoVITS training (s2_train.py for v1/v2, s2_train_v3.py for v3/v4, or s2_train_v3_lora.py for LoRA)

After training completes, your custom weights are saved and can be loaded for inference.

5.3 Cross-Lingual Synthesis

GPT-SoVITS supports synthesizing speech in a different language from the reference audio. For example, clone a Chinese speaker and have them speak English:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This English text will be spoken in a Chinese voice.",
    "text_lang": "en",
    "ref_audio_path": "chinese_speaker.wav",
    "prompt_text": "这是中文参考文本。",
    "prompt_lang": "zh"
  }' \
  --output cross_lingual.wav

5.4 Batch Processing Long Text

For long documents, configure text splitting and batch processing:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Very long text goes here... multiple paragraphs...",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference transcript.",
    "prompt_lang": "en",
    "text_split_method": "cut5",
    "batch_size": 4,
    "parallel_infer": true,
    "split_bucket": true
  }' \
  --output long_output.wav

The text_split_method parameter controls how text is chunked. "cut5" is the default and works well for most cases.

5.5 Adjusting Speech Speed

Control playback speed with the speed_factor parameter:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This will be spoken at 1.2x speed.",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference.",
    "prompt_lang": "en",
    "speed_factor": 1.2
  }' \
  --output fast_speech.wav

Values above 1.0 speed up; below 1.0 slow down.

5.6 Using Multiple Reference Audios

For better voice capture, pass additional reference clips via aux_ref_audio_paths:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Synthesized with multiple references.",
    "text_lang": "en",
    "ref_audio_path": "ref1.wav",
    "aux_ref_audio_paths": ["ref2.wav", "ref3.wav"],
    "prompt_text": "Primary reference transcript.",
    "prompt_lang": "en"
  }' \
  --output multi_ref.wav

5.7 Audio Super-Resolution (v3)

SoVITS v3 outputs at 24 kHz natively. Enable super-resolution to upsample to 48 kHz:

curl -X POST http://localhost:9880/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "High quality v3 output.",
    "text_lang": "en",
    "ref_audio_path": "reference.wav",
    "prompt_text": "Reference transcript.",
    "prompt_lang": "en",
    "super_sampling": true
  }' \
  --output hd_output.wav

The super-resolution uses the AP-BWE model (tools/audio_sr.py) internally. This is only relevant for v3 -- v4 outputs at 48 kHz natively, and v1/v2 output at 32 kHz.

5.8 Denoising Audio

Clean up noisy recordings before using them as training data or references:

python tools/cmd-denoise.py --input noisy.wav --output clean.wav

5.9 Controlling Randomness and Reproducibility

For reproducible outputs, set a fixed seed:

{
  "text": "Reproducible output.",
  "text_lang": "en",
  "ref_audio_path": "reference.wav",
  "prompt_text": "Reference.",
  "prompt_lang": "en",
  "seed": 42,
  "temperature": 0.8,
  "top_k": 10,
  "top_p": 0.9
}

Lower temperature produces more deterministic (but potentially flatter) speech. Higher values add variation. The repetition_penalty (default 1.35) discourages the GPT model from repeating tokens.

5.10 Choosing the Right Model Version

Important

v3 and v4 do not support streaming inference. If your application requires real-time audio delivery, use v2, v2Pro, or v2ProPlus.

5.11 Controlling v3/v4 Quality with Sample Steps

The sample_steps parameter controls generation quality vs. speed for v3 and v4:

v3 options: 4, 8, 16, 32, 64, 128 (default: 32) v4 options: 4, 8, 16, 32 (default: 8)

Higher values produce better audio but take longer. Halving the steps roughly halves generation time.

{
  "text": "Quick draft.",
  "text_lang": "en",
  "ref_audio_path": "ref.wav",
  "prompt_text": "Reference.",
  "prompt_lang": "en",
  "sample_steps": 8
}

5.12 Using the UVR5 Vocal Separator

The UVR5 tool removes instrumentals from music or separates vocals from background noise:

python tools/uvr5/webui.py

Opens at http://localhost:9873. Supported model architectures:

• BS-RoFormer -- state-of-the-art separation quality
• MDXNet -- good quality, faster
• VR -- legacy, widest model variety

Upload your audio, select the model, and download the separated vocal track to use as training data.

5.13 Python Integration

Use the API programmatically from Python:

import requests

response = requests.post("http://localhost:9880/tts", json={
    "text": "Hello from Python!",
    "text_lang": "en",
    "ref_audio_path": "/absolute/path/to/reference.wav",
    "prompt_text": "This is the reference transcript.",
    "prompt_lang": "en",
    "media_type": "wav"
})

with open("output.wav", "wb") as f:
    f.write(response.content)

print(f"Generated {len(response.content)} bytes of audio")

5.14 Switching Models at Runtime

You can switch between different voice models without restarting the API server:

import requests

# Switch to a custom fine-tuned model
requests.get("http://localhost:9880/set_gpt_weights", params={
    "weights_path": "/path/to/custom_gpt.ckpt"
})
requests.get("http://localhost:9880/set_sovits_weights", params={
    "weights_path": "/path/to/custom_sovits.pth"
})

# Now all TTS requests use the new model
response = requests.post("http://localhost:9880/tts", json={
    "text": "Speaking with the new voice model.",
    "text_lang": "en",
    "ref_audio_path": "new_ref.wav",
    "prompt_text": "New reference.",
    "prompt_lang": "en"
})

6. Troubleshooting

6.1 Reference Audio Rejected

Error: 参考音频在3~10秒范围外，请更换！ (Reference audio outside 3-10 second range)

The reference audio must be between 3 and 10 seconds long. Trim your clip:

ffmpeg -i long_reference.wav -ss 0 -t 8 trimmed_reference.wav

6.2 Empty Reference Audio Path

Error: ref_audio_path cannot be empty, when the reference audio is not set using set_ref_audio()

You must either:

• Pass ref_audio_path in every TTS request, or
• Set a default reference using the /set_refer_audio endpoint before making requests

6.3 Empty or Invalid Text

Error: 请输入有效文本 (Please enter valid text)

The text parameter cannot be empty or whitespace-only. Ensure you are sending actual text content.

6.4 Streaming with v3/v4 Models

Error: SoVits V3/4模型不支持流式推理模式 (SoVITS V3/4 models do not support streaming inference)

v3 and v4 use different vocoders (BigVGAN and HiFi-GAN respectively) that are not compatible with streaming. Set streaming_mode to 0 or false, or switch to a v1/v2/v2Pro model.

6.5 use_libuv RuntimeError

Error: RuntimeError: use_libuv was requested but PyTorch was build without libuv support

Reported in issues #1982 and #1357. This is a PyTorch build configuration issue. Solutions:

1. Set the environment variable before launching:

   export USE_LIBUV=0
   python webui.py
   

2. Or reinstall PyTorch from a build that includes libuv support.

6.6 CUDA sm80/sm370 FATAL Errors

Error: FATAL error mentioning sm80 and sm370 during inference.

Reported in issues #2766 and #2388. This usually means a CUDA architecture mismatch between your GPU and the installed PyTorch build. Solutions:

1. Verify your GPU's compute capability matches the installed CUDA toolkit.
2. Reinstall PyTorch with the correct CUDA version for your GPU.
3. On older GPUs, try disabling half precision: export is_half=False.

6.7 ASGI Application Exception

Error: Exception in ASGI application

Reported in issue #2762. Common causes:

1. Model weights not found at the configured path -- verify paths in tts_infer.yaml.
2. Insufficient GPU memory -- reduce batch_size or switch to CPU.
3. Corrupted model files -- re-download pretrained weights.

Warning

If the ASGI error occurs immediately on startup, check that all model files referenced in your config actually exist. Missing weights files are the most common cause.

6.8 install.ps1 Not Working

Reported in issue #2757. The PowerShell install script may fail due to:

1. Execution policy restrictions -- run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned first.
2. Network issues downloading models -- try -Source HF-Mirror or -Source ModelScope.
3. Fall back to manual installation: pip install -r requirements.txt and download models manually.

6.9 GPU Not Detected (ROCm)

Reported in issue #2743. AMD GPU with ROCm 7.2 on Windows may not be detected. This is a known limitation. Workarounds:

1. Use Linux with ROCm 6.x instead.
2. Fall back to CPU mode: export is_half=False and set device: cpu in tts_infer.yaml.

6.10 PermissionError: Permission Denied

Reported in issue #2729. Common causes:

1. Model files are read-only or owned by a different user.
2. Output directory does not exist or is not writable.
3. On Windows, another process has the file open.

Fix: ensure write permissions on the output directory and that no other process is locking model files.

Caution

On Windows, if the WebUI crashes mid-inference, it may leave lock files on temporary audio. Restart the application and ensure the TEMP directory is writable.

6.11 Out of GPU Memory (OOM)

If inference or training runs out of VRAM:

1. Reduce batch_size to 1.
2. Enable half precision (is_half: true).
3. Use a smaller model version (v1/v2 instead of v3/v4).
4. Close other GPU-consuming applications.
5. For training, reduce the training batch size in the WebUI.

6.12 Deprecated Dependencies

Reported in issue #2761. Some dependencies may emit deprecation warnings or fail outright. Keep your environment up to date:

pip install -r requirements.txt --upgrade

If specific packages conflict, create a fresh virtual environment:

python -m venv venv
source venv/bin/activate  # Linux
# or: .\venv\Scripts\activate  # Windows
pip install -r requirements.txt

7. FAQ

Q: What is the minimum audio needed for voice cloning? A: For zero-shot cloning (no training), you need a single 3--10 second clip plus its transcript. For fine-tuning, approximately 1 minute of clean audio produces noticeably better results. More data (up to 5 minutes) continues to improve quality with diminishing returns.

Q: Which model version should I use? A: Start with v2 (the default). It offers the best balance of quality, speed, and feature support including streaming. Move to v3 or v4 if you need the highest audio fidelity and don't need streaming. Use v2Pro or v2ProPlus if speaker similarity is your top priority.

Q: Can I mix languages in a single synthesis request? A: Yes. Set text_lang to auto and write mixed-language text. The system detects language boundaries and applies appropriate phoneme processing per segment. For example: "Hello, 你好, こんにちは" with text_lang: "auto".

Q: What audio formats are supported for reference clips? A: WAV is the most reliable. The system uses ffmpeg internally, so any format ffmpeg can decode will work (MP3, FLAC, OGG, etc.). The output format is controlled by the media_type parameter: wav, ogg, or aac.

Q: Can I run GPT-SoVITS on CPU only? A: Yes, but it will be significantly slower. Set device: cpu in tts_infer.yaml and is_half: false (CPU does not support FP16). Use the -Device CPU flag with the Windows install script.

Q: How do I use a fine-tuned model with the API? A: Either update the model paths in GPT_SoVITS/configs/tts_infer.yaml before starting the server, or switch models at runtime using the /set_gpt_weights and /set_sovits_weights endpoints.

Q: Why does my output sound robotic or distorted? A: Common causes: (1) reference audio is too short or too noisy, (2) reference transcript is inaccurate, (3) half precision issues on older GPUs (try is_half: false), (4) mismatched model versions (e.g., loading v1 weights with v2 config).

Q: What sample rate does the output use? A: v1 and v2/v2Pro/v2ProPlus output at 32 kHz. v3 outputs at 24 kHz (48 kHz with super_sampling: true). v4 outputs at 48 kHz natively.

Q: How do I expose the API to other machines? A: API v2 binds to 127.0.0.1 by default (localhost only). Start with -a 0.0.0.0 to listen on all interfaces. API v1 already binds to 0.0.0.0 by default. Remember to configure your firewall accordingly.

Q: Can I run multiple model versions simultaneously? A: Not in a single server instance. Each API server process loads one GPT model and one SoVITS model at a time. To serve multiple versions, run multiple server instances on different ports.

Q: What is the prompt_text parameter? A: It is the transcript of your reference audio clip. It helps the model understand what is being said in the reference, improving voice matching and prosody. It is optional for v1/v2 but required for v3.

Q: How do I handle very long text? A: The system automatically splits long text into chunks based on text_split_method. Increase batch_size and enable parallel_infer for faster processing. The split_bucket option groups similar-length chunks for more efficient batching.

Q: Is there a maximum text length? A: There is no hard-coded maximum, but extremely long texts will consume more memory and time. The text splitting mechanism handles arbitrarily long inputs by chunking them before inference.

Q: Can I use GPT-SoVITS commercially? A: Check the repository's license file. Voice cloning technology carries ethical and legal considerations -- always ensure you have permission to clone a specific person's voice and comply with local regulations.

Q: What is the difference between API v1 and API v2? A: API v2 is config-driven (reads from tts_infer.yaml), binds to localhost by default (safer), has a cleaner parameter interface, and is the actively maintained version. API v1 is CLI-driven (all options via flags), binds to 0.0.0.0 by default, and is considered legacy.

Q: How do I improve speaker similarity? A: (1) Use v2Pro or v2ProPlus which include speaker verification embeddings. (2) Provide multiple reference audios via aux_ref_audio_paths. (3) Ensure reference audio is clean and representative of the target voice. (4) Fine-tune on more data from the target speaker.

For architecture details, deployment configuration, security considerations, and internal pipeline documentation, see the Admin Guide.