ElevenLabs Sound Effects v2 API：効果音の生成とダウンロード

TL;DR

• ElevenLabs Sound Effects v2 はテキストの説明を 1 本の MP3 効果音に変換します。モデルページを開く と既存のサンプルを試聴できます。
• リクエストした再生時間に応じて課金され、1 秒あたり $0.0029 です。2 秒なら $0.0058。価格は 2026 年 10 月 25 日に確認済みです。価格を確認。
• HiAPI の /v1/tasks インターフェースでタスクを送信して taskId を取得し、その後で結果を照会します。

Python サンプルを実行する前に、同じ Python 環境で python -m pip install requests を実行してください。

まず 2 秒のサンプルを聴いてみる

これはモデルページにある映画風の低周波インパクトのサンプルです。以下にその完全なプロンプトと音声を掲載します。

Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.

完全な効果音を試聴する

このプロンプトで生成 →

elevenlabs/sound-effects-v2、2 秒、prompt_influence: 0.3、loop: false、MP3、現行価格で $0.0058。プリフィルリンクを開いた後に、再生時間と制御項目を別途設定してください。

パラメータの入力方法

フィールド	必須	値と説明
model	はい	elevenlabs/sound-effects-v2 をリクエストボディの最上位に置く
input.prompt	はい	1〜450 文字。音、素材、動作、空間を記述する
input.duration_seconds	はい	0.5〜22 秒、小数も可。必ず明示的に指定する
input.prompt_influence	いいえ	0〜1、デフォルトは 0.3
input.loop	いいえ	ブール値、デフォルトは false

1 回につき 1 本の 44.1 kHz、128 kbps の MP3 を返します。loop は冒頭と末尾をできるだけつなげるためのもので、音声を延長はしません。長い背景音は再生側でループさせてください。

curl：最初の効果音を送信する

サンプルを実行すると実際のタスクが作成され、再生時間に応じて課金されます。キーはサーバーの環境変数 HIAPI_API_KEY に入れてください。同じ業務リクエストのリトライでは冪等キーを再利用し、新しい効果音リクエストには新しいキーを使用します。

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sfx-example-001" \
  -d '
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}'

作成レスポンスの data.taskId からタスク ID を取得し、続いて GET /v1/tasks/<taskId> を照会します。

Python：送信、待機、保存

requests をインストールしてから、以下のサンプルを実行してください。success と fail のみを終端状態として扱い、queued、handling、archiving はいずれも引き続き待機します。

import json
import os
import time
from pathlib import Path
import requests

api = "https://api.hiapi.ai"
key = os.environ.get("HIAPI_API_KEY", "")
if not key or any(ord(c) < 33 or ord(c) > 126 for c in key) or any(c in key for c in (chr(34), chr(39))):
    raise SystemExit("Check the key environment variable; do not print its value")
headers = {"Authorization": f"Bearer {key}"}
payload = json.loads(r'''
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}
''')
response = requests.post(
    f"{api}/v1/tasks", json=payload,
    headers={**headers, "Idempotency-Key": "sfx-example-001"}, timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
Path("task-id.txt").write_text(task_id, encoding="utf-8")
print("Task ID saved to task-id.txt:", task_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{api}/v1/tasks/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["data"]
    if task["status"] == "fail":
        raise RuntimeError(task.get("error", "Task failed"))
    if task["status"] == "success":
        audio = next(item for item in task["output"] if item.get("type") == "audio")
        result = requests.get(audio["url"], timeout=120)
        result.raise_for_status()
        Path("effect.mp3").write_bytes(result.content)
        print("Saved effect.mp3")
        break
    time.sleep(4)
else:
    raise TimeoutError(f"Keep this taskId for later lookup: {task_id}")

本番投入前の 3 つのチェック

1. 失敗とタイムアウト。 HTTP ステータスとタスクの error を確認します。サンプルは待機がタイムアウトした後も taskId を保持して後から照会を続け、重複送信を避けます。
2. パラメータエラー。 400 INVALID_REQUEST の場合は、必須の再生時間、数値範囲、フィールド型を確認してください。そのまま再試行しないでください。失敗したタスクの事前引き落とし分は返金されます。
3. 結果の保存。 成功後は音声 URL を読み取って速やかに保存します。バッチタスクでは callback.url を設定して終端状態の通知を受け取ることもできます。

よくある質問

どのくらいの長さの効果音を生成できますか？

1 回あたり 0.5〜22 秒で、小数秒も可能です。duration_seconds は必須です。

loop は効果音を自動的に延長しますか？

いいえ。冒頭と末尾のつながりを改善するためのもので、長さは duration_seconds によって決まります。

2 秒の効果音の料金はいくらですか？

1 秒あたり $0.0029 で計算し、2 秒なら $0.0058 です。失敗したタスクは事前引き落とし分が返金されます。

いつ音声をダウンロードできますか？

status が success になるのを待ってから、output 内の type が audio のエントリを読み取ってください。archiving 段階では引き続き待機します。

さらに連携する

• 完全なモデルドキュメント
• タスク状態とコールバック
• キーエラーのトラブルシューティング
• サンプルのプロンプトをコピーして、モデルページで効果音を作成する