sound-effects

用途

该技能用于根据文字描述生成音效，依托 ElevenLabs 的文本转音效（Text to Sound Effects）能力，可用于创建音效、生成音频纹理、制作环境音以及影视化声音等场景。

主要能力

支持循环（loop）生成无缝循环音效，仅 v2 模型可用。
支持自定义时长（duration_seconds），范围为 0.5–30 秒；若为 null 则自动计算。
支持提示词贴合度控制（prompt_influence），取值 0–1，默认 0.3，用于控制生成结果对提示词的遵循程度。
支持多种输出格式，例如 mp3_44100_128（默认）、pcm_44100、opus_48000_128、ulaw_8000，以及 mp3、pcm、ulaw、alaw、opus 系列的其他采样率与码率选项。

使用方式

可通过 Python、JavaScript 或 cURL 调用。

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 示例（仅使用 @elevenlabs/* 包）：

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–30 秒。
prompt_influence：number | null，默认 0.3，对提示词的遵循程度（0–1）。
loop：boolean，默认 false，生成无缝循环音效（仅 v2 模型）。

带参数的示例：

# 循环环境音，10 秒
audio = client.text_to_sound_effects.convert(
    text="Gentle forest ambiance with birds chirping",
    duration_seconds=10.0,
    prompt_influence=0.5,
    loop=True,
)

# 短 UI 音效，高提示词贴合度
audio = client.text_to_sound_effects.convert(
    text="Soft notification chime",
    duration_seconds=1.0,
    prompt_influence=0.8,
)

输出格式可作为查询参数（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。

提示词建议：具体描述（“Heavy rain on a tin roof” 优于 “Rain”）；组合元素（“Footsteps on gravel with distant traffic”）；指定风格（“Cinematic braam, horror” 或 “8-bit retro jump sound”）；说明情绪/语境（“Eerie wind howling through an abandoned building”）。

错误处理：

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 超出速率限制。

适用场景

适合需要快速生成音效素材的制作流程，例如为视频、游戏、播客或交互界面制作环境音、氛围声和短音效。

限制

时长范围为 0.5–30 秒；loop 仅 v2 模型支持；使用需配置 ElevenLabs API 密钥。安装方式与收费、价格等信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制