sound-effects

ElevenLabs 音效

根据文本描述生成音效——支持循环播放、自定义时长和提示词遵循度控制。

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

快速开始

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.text_to_sound_effects.convert(
    text="Thunder rumbling in the distance with light rain",
)

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

JavaScript

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

const client = new ElevenLabsClient();
const audio = await client.textToSoundEffects.convert({
  text: "Thunder rumbling in the distance with light rain",
});
audio.pipe(createWriteStream("thunder.mp3"));

CLI

elevenlabs text-to-sound-effects convert \
  --text "Thunder rumbling in the distance with light rain" \
  --output thunder.mp3

参数

参数	类型	默认值	描述
text	string（必填）	—	对所需音效的描述
model_id	string	eleven_text_to_sound_v2	要使用的模型
duration_seconds	number | null	null（自动）	时长为 0.5–30s；若为 null，则自动计算
prompt_influence	number | null	0.3	遵循提示词的程度（0–1）
loop	boolean	false	生成可无缝循环播放的音效（仅限 v2 模型）

参数示例

# Looping ambient sound, 10 seconds
audio = client.text_to_sound_effects.convert(
    text="Gentle forest ambiance with birds chirping",
    duration_seconds=10.0,
    prompt_influence=0.5,
    loop=True,
)

# Short UI sound, high prompt adherence
audio = client.text_to_sound_effects.convert(
    text="Soft notification chime",
    duration_seconds=1.0,
    prompt_influence=0.8,
)

输出格式

传入 --output-format（CLI），或将 output_format 作为 SDK 参数传入：

格式	描述
mp3_44100_128	MP3，44.1kHz，128kbps（默认）
pcm_44100	原始未压缩 CD 音质
opus_48000_128	Opus，48kHz，128kbps——高效压缩
ulaw_8000	μ-law，8kHz——电话音频

完整列表：mp3_22050_32、mp3_24000_48、mp3_44100_32、mp3_44100_64、mp3_44100_96、mp3_44100_128、mp3_44100_192、pcm_8000、pcm_16000、pcm_22050、pcm_24000、pcm_32000、pcm_44100、pcm_48000、wav_8000、wav_16000、wav_22050、wav_24000、wav_32000、wav_44100、wav_48000、ulaw_8000、alaw_8000、opus_48000_32、opus_48000_64、opus_48000_96、opus_48000_128、opus_48000_192。

提示词技巧

• 描述具体：“锡皮屋顶上的大雨” > “雨”
• 组合多个元素：“碎石路上的脚步声，伴有远处的交通声”
• 指定风格：“电影感的低沉轰鸣，恐怖风格”或“8-bit 复古跳跃音效”
• 提及氛围或背景：“诡异的风呼啸着穿过一栋废弃建筑”

错误处理

try:
    audio = client.text_to_sound_effects.convert(text="Explosion")
except Exception as e:
    print(f"API error: {e}")

常见错误：

• 401：API 密钥无效
• 422：参数无效（检查时长范围和 prompt_influence 范围）
• 429：超出速率限制

参考资料

• 安装指南