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	字串 (必填)	—	所需音效的描述
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 模型)

含參數的範例

# 循環環境音，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,
)

輸出格式

將 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="爆炸")
except Exception as e:
    print(f"API 錯誤：{e}")

常見錯誤：

• 401：API 金鑰無效
• 422：參數無效 (檢查持續時間範圍、prompt_influence 範圍)
• 429：超出速率限制

參考資料

• 安裝指南