sound-effects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ElevenLabs Sound Effects

ElevenLabs 音效生成

Generate sound effects from text descriptions — supports looping, custom duration, and prompt adherence control.

Setup: See Installation Guide. For JavaScript, use
@elevenlabs/*
packages only.

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

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

Quick Start

快速开始

Python

python

from elevenlabs.client 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)

python

from elevenlabs.client 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

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"));

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

bash

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

bash

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

Parameters

参数

Parameter	Type	Default	Description
`text`	string (required)	—	Description of the desired sound effect
`model_id`	string	`eleven_text_to_sound_v2`	Model to use
`duration_seconds`	number \| null	null (auto)	Duration 0.5–30s; auto-calculated if null
`prompt_influence`	number \| null	0.3	How closely to follow the prompt (0–1)
`loop`	boolean	false	Generate a seamlessly looping sound (v2 model only)

参数	类型	默认值	说明
`text`	字符串（必填）	—	所需音效的描述
`model_id`	字符串	`eleven_text_to_sound_v2`	使用的模型
`duration_seconds`	数字 \| null	null（自动）	时长0.5–30秒；若为null则自动计算
`prompt_influence`	数字 \| null	0.3	遵循提示词的程度（0–1）
`loop`	布尔值	false	生成可无缝循环的音效（仅v2模型支持）

Examples with Parameters

带参数的示例

python

undefined

python

undefined

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, )

undefined

audio = client.text_to_sound_effects.convert( text="Soft notification chime", duration_seconds=1.0, prompt_influence=0.8, )

undefined

Output Formats

输出格式

Pass

output_format

as a query parameter (cURL) or SDK parameter:

Format	Description
`mp3_44100_128`	MP3 44.1kHz 128kbps (default)
`pcm_44100`	Raw uncompressed CD quality
`opus_48000_128`	Opus 48kHz 128kbps — efficient compressed
`ulaw_8000`	μ-law 8kHz — telephony

Full list:

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

传递

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

Prompt Tips

提示词技巧

Be specific: "Heavy rain on a tin roof" > "Rain"
Combine elements: "Footsteps on gravel with distant traffic"
Specify style: "Cinematic braam, horror" or "8-bit retro jump sound"
Mention mood/context: "Eerie wind howling through an abandoned building"

具体明确："Heavy rain on a tin roof"（铁皮屋顶上的大雨）优于"Rain"（雨）
组合元素："Footsteps on gravel with distant traffic"（砾石上的脚步声加远处的车流声）
指定风格："Cinematic braam, horror"（电影式低沉轰鸣，恐怖风格）或"8-bit retro jump sound"（8位复古跳跃音效）
提及情绪/场景："Eerie wind howling through an abandoned building"（废弃建筑中呼啸的诡异风声）

Error Handling

错误处理

python

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

Common errors:

401: Invalid API key
422: Invalid parameters (check duration range, prompt_influence range)
429: Rate limit exceeded

python

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：超出调用频率限制

References

参考资料

Installation Guide

安装指南