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～30秒。null の場合は自動計算
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 ではパラメータとして 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

プロンプトのヒント

• 具体的に記述する: 「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: レート制限を超過

リファレンス

• インストールガイド