sound-effects

ElevenLabs 音效生成

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

设置： 参见安装指南。对于JavaScript，仅使用@elevenlabs/*包。

快速开始

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.text_to_sound_effects.convert(
    text="远处雷声隆隆，伴有小雨",
)

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: "远处雷声隆隆，伴有小雨",
});
audio.pipe(createWriteStream("thunder.mp3"));

cURL

curl -X POST "https://api.elevenlabs.io/v1/sound-generation" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "远处雷声隆隆，伴有小雨"}' \
  --output thunder.mp3

参数

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

带参数的示例

# 循环环境音，10秒
audio = client.text_to_sound_effects.convert(
    text="轻柔的森林氛围，鸟鸣声",
    duration_seconds=10.0,
    prompt_influence=0.5,
    loop=True,
)

# 短UI音效，高提示词遵循度
audio = client.text_to_sound_effects.convert(
    text="轻柔的通知提示音",
    duration_seconds=1.0,
    prompt_influence=0.8,
)

输出格式

通过查询参数（cURL）或SDK参数传递output_format：

格式	描述
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, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192。

提示词技巧

• 具体描述："铁皮屋顶上的大雨" > "雨"
• 组合元素："砾石上的脚步声，远处有车流"
• 指定风格："电影震撼音，恐怖" 或 "8位复古跳跃音"
• 提及情绪/场景："废弃建筑中阴森的风声"

错误处理

try:
    audio = client.text_to_sound_effects.convert(text="爆炸")
except Exception as e:
    print(f"API错误: {e}")

常见错误：

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

参考

• 安装指南