ElevenLabs Sound Effects v2 音效 API

TL;DR

ElevenLabs Sound Effects v2 把文字描述转成一条 MP3 音效；打开模型页可以试听现有案例。
按请求时长计费，每秒 $0.0029；2 秒为 $0.0058，价格已于 2026 年 10 月 25 日核对，查看价格。
通过 HiAPI /v1/tasks 接口提交任务拿 taskId，再查询结果。

运行 Python 示例前，在同一个 Python 环境执行 python -m pip install requests。

先听一个两秒案例

这是模型页已有的电影感低频冲击案例，下面保留它的完整提示词和音频。

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

一次返回一条 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}")