sound-effects

ElevenLabs 音效

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

**设置：**请参阅安装指南。对于 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"));

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": "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 作为查询参数（cURL）或 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、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="Explosion")
except Exception as e:
    print(f"API error: {e}")

常见错误：

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

参考资料

• 安装指南