voice-changer

ElevenLabs Voice Changer

将音频录音中的声音转换为另一种目标声音。Voice Changer（以前称为 Speech-to-Speech — API 端点和 SDK 方法仍使用 speech_to_speech / speechToSpeech 这一名称）会保留原始表演——情绪、语速、语调、呼吸、耳语、笑声、哭声——只替换说话者。

**在编写任何代码之前完成设置：**如果尚未为此项目设置 ELEVENLABS_API_KEY，请先在应用文件夹中运行 npx -y @elevenlabs/cli@latest onboard init，并按照输出提示操作：它会为用户登录并保存项目密钥，因此无需手动复制密钥。否则，请参阅安装指南。对于 JavaScript，请仅使用 @elevenlabs/* 包。

关键事实

• **输入时长上限：**每个请求最多 5 分钟——更长的录音需分段处理，再拼接输出。
• **文件大小上限：**每个请求最多 50 MB——如果源文件更大，请压缩为 MP3。
• **计费方式：**每分钟处理的音频计费 1,000 个字符（按时长计费，而非按文本计费）。
• 推荐模型：eleven_multilingual_sts_v2——即使对于纯英语内容，其表现通常也优于 eleven_english_sts_v2。

快速开始

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

with open("source.mp3", "rb") as audio_file:
    audio_stream = client.speech_to_speech.convert(
        voice_id="JBFqnCBsd6RMkjVDRZzb",  # George
        audio=audio_file,
        model_id="eleven_multilingual_sts_v2",
        output_format="mp3_44100_128",
    )

with open("converted.mp3", "wb") as f:
    for chunk in audio_stream:
        f.write(chunk)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream, createWriteStream } from "fs";

const client = new ElevenLabsClient();

const audioStream = await client.speechToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  audio: createReadStream("source.mp3"),
  modelId: "eleven_multilingual_sts_v2",
  outputFormat: "mp3_44100_128",
});

audioStream.pipe(createWriteStream("converted.mp3"));

CLI

elevenlabs speech-to-speech convert \
  --voice-id JBFqnCBsd6RMkjVDRZzb \
  --audio source.mp3 \
  --model-id eleven_multilingual_sts_v2 \
  --output-format mp3_44100_128 \
  --output converted.mp3

参数

参数	类型	默认值	描述
voice_id	string（必填）	—	目标声音。可使用预制声音 ID、克隆声音或声音库中的声音
audio	file（必填）	—	源音频；其表演（情绪、时机、表达方式）将得到保留
model_id	string	eleven_english_sts_v2	29 种语言使用 eleven_multilingual_sts_v2，仅英语使用 eleven_english_sts_v2
output_format	string	mp3_44100_128	参见下方的输出格式表
voice_settings	JSON string	—	仅对本次请求覆盖已保存的声音设置
seed	integer	—	尽力实现确定性采样（0 – 4294967295）
remove_background_noise	boolean	false	转换前对输入音频运行隔离模型
file_format	string	other	other 表示任意编码音频；pcm_s16le_16 表示 16 位 PCM 单声道 @ 16kHz 小端格式（延迟更低）
optimize_streaming_latency	int（查询参数）	—	0–4。以质量换取延迟。4 速度最快，但会禁用文本规范化
enable_logging	boolean（查询参数）	true	设为 false 可启用零保留模式（仅限企业版——会禁用历史记录和拼接）

模型

模型 ID	语言	适用场景
eleven_multilingual_sts_v2	29 种	推荐用于所有场景——即使处理英语音频，表现通常也优于英语模型
eleven_english_sts_v2	英语	API 默认模型——仅英语场景的后备选项

此处只能使用 can_do_voice_conversion 属性为 true 的模型。Voice Changer 目前没有低延迟的“flash/turbo”档位——如有此需求，请使用 pcm_s16le_16 输入、opus_* / 低比特率 mp3_* 输出，并提高 optimize_streaming_latency。

语言（eleven_multilingual_sts_v2）

英语（美国、英国、澳大利亚、加拿大）、日语、中文、德语、印地语、法语（法国、加拿大）、韩语、葡萄牙语（巴西、葡萄牙）、意大利语、西班牙语（西班牙、墨西哥）、印度尼西亚语、荷兰语、土耳其语、菲律宾语、波兰语、瑞典语、保加利亚语、罗马尼亚语、阿拉伯语（沙特阿拉伯、阿联酋）、捷克语、希腊语、芬兰语、克罗地亚语、马来语、斯洛伐克语、丹麦语、泰米尔语、乌克兰语、俄语。

目标声音

可使用预制声音、克隆声音或声音库中的任意声音 ID。

热门声音：

• JBFqnCBsd6RMkjVDRZzb — George（男性，叙述风格）
• EXAVITQu4vr4xnSDxMaL — Sarah（女性，柔和）
• onwK4e9ZLuTAKqWW03F9 — Daniel（男性，权威）
• XB0fDUnXU5powFXDhCwa — Charlotte（女性，对话风格）

voices = client.voices.get_all()
for voice in voices.voices:
    print(f"{voice.voice_id}: {voice.name}")

从 URL 转换

import requests
from io import BytesIO
from elevenlabs import ElevenLabs

client = ElevenLabs()

audio_url = "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

audio_stream = client.speech_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    audio=audio_data,
    model_id="eleven_multilingual_sts_v2",
    output_format="mp3_44100_128",
)

with open("converted.mp3", "wb") as f:
    for chunk in audio_stream:
        f.write(chunk)

语音设置覆盖

在不更改已保存默认设置的情况下，为单次请求微调目标语音：

from elevenlabs import VoiceSettings

audio_stream = client.speech_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    audio=audio_file,
    model_id="eleven_multilingual_sts_v2",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.0,
        use_speaker_boost=True,
    ),
)

• 稳定性：越低，情感变化越丰富（越自由地跟随源音频）；越高，表达越稳定。
• 相似度增强：越高，音色越接近目标语音，但也可能放大源音频中的瑕疵。
• 风格：夸大目标语音的独特特征（v2+ 模型）。
• 说话人增强：通过后处理提升目标语音的清晰度。

清理嘈杂的源音频

如果输入录音有噪声，可以先使用 voice-isolator 技能进行预处理，或传入 remove_background_noise=True，一次调用即可完成处理：

audio_stream = client.speech_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    audio=audio_file,
    model_id="eleven_multilingual_sts_v2",
    remove_background_noise=True,
)

更干净的输入几乎总能带来更好的转换效果——模型需要匹配音素和韵律，背景噪声会造成干扰。

低延迟 PCM 输入

如果你已有 16-bit PCM 单声道 @ 16kHz 的原始音频，传入 file_format="pcm_s16le_16" 可跳过解码并降低延迟：

audio_stream = client.speech_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    audio=pcm_bytes,
    model_id="eleven_multilingual_sts_v2",
    file_format="pcm_s16le_16",
)

还可以将 optimize_streaming_latency（0–4）作为查询参数一起使用，以牺牲一定音质为代价进一步降低延迟。

输出格式

格式	描述
mp3_44100_128	MP3 44.1kHz 128kbps（默认）——适用于网页和应用
mp3_44100_192	MP3 44.1kHz 192kbps（Creator+）——音质更高
mp3_44100_64	MP3 44.1kHz 64kbps——文件更小
mp3_22050_32	MP3 22.05kHz 32kbps——体积最小的 MP3
pcm_16000	原始 PCM 16kHz——适用于实时处理流水线
pcm_24000	原始 PCM 24kHz——兼顾流媒体效果
pcm_44100	原始 PCM 44.1kHz（Pro+）——CD 音质
pcm_48000	原始 PCM 48kHz（Pro+）——最高音质
ulaw_8000	μ-law 8kHz——适用于 Twilio／电话系统
alaw_8000	A-law 8kHz——适用于电话系统
opus_48000_64	Opus 48kHz 64kbps——高效流媒体格式

确定性输出

传入 seed，让相同输入的重复转换尽可能返回相同的音频——适用于测试和 A/B 对比。

audio_stream = client.speech_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    audio=audio_file,
    model_id="eleven_multilingual_sts_v2",
    seed=12345,
)

输入音频最佳实践

转换质量受输入录音限制——模型只能替换音色，无法挽救质量差的源音频。以下是一些实用建议：

• 充分表达情绪。 轻声说话、大喊、大笑、哭泣——模型会保留这些表现。平淡的输入只会得到平淡的输出。
• 注意麦克风增益。 音量太低，模型会漏检音素；音量太高，削波失真会影响转换效果。应确保峰值合适且没有削波。
• 口音和语速节奏来自源音频，而非目标语音。 如果你用美式口音朗读，并选择英国口音的“George”语音作为目标，得到的会是 George 的音色搭配美式口音。若要配成另一种口音或语言，请录制使用目标口音或语言的人声，再转换为克隆语音或语音库中的语音。
• 先清理噪声。 传入 remove_background_noise=True，或在转换前使用 voice-isolator 技能处理源音频。噪声对这里的影响比对 TTS 更大。
• 拆分较长录音。 超过 5 分钟的录音必须分块。请在自然停顿处剪切，逐段转换，再将生成的音频拼接起来。

常见工作流

• 为旁白换声——保留临时录音的演绎效果，替换为另一种旁白语音。
• 本地化／配音——将配音转换为同一说话者的另一语言克隆语音（使用 eleven_multilingual_sts_v2）。
• 创建角色语音——亲自演绎台词，再转换为适用于游戏或动画的鲜明角色语音。
• 匿名化说话者——将可识别的语音替换为中性预制语音，同时保留说话内容和表达方式。
• 搭配 voice-isolator 使用——对于嘈杂的现场录音，先分离源语音（或设置 remove_background_noise=True），再进行转换。
• 搭配语音克隆使用——从短音频样本克隆目标语音，然后在此处使用其 voice_id 作为转换目标。

错误处理

try:
    audio_stream = client.speech_to_speech.convert(
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        audio=audio_file,
        model_id="eleven_multilingual_sts_v2",
    )
except Exception as e:
    print(f"Voice changer failed: {e}")

常见错误：

• 401：API 密钥无效
• 422：参数无效（请检查 voice_id、model_id 或 file_format 是否与提供的音频匹配）
• 429：超出速率限制

参考资料

• 安装指南