ElevenLabs Sound Effects v2 API Guide

TL;DR

ElevenLabs Sound Effects v2 turns a written description into one MP3 effect. Open the model page to hear existing examples.
Billing follows requested duration: $0.0029 per second, or $0.0058 for 2 seconds, checked October 25, 2026. View pricing.
Submit through HiAPI /v1/tasks, keep the taskId, and retrieve the finished result.

Before running the Python examples, install the dependency in the same environment: python -m pip install requests.

Listen to a two-second example

This cinematic impact is an existing model-page example. Its full prompt and audio are linked below.

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

Listen to the complete effect

Generate with this prompt →

elevenlabs/sound-effects-v2, 2 seconds, prompt_influence: 0.3, loop: false, MP3, $0.0058 at the current rate. Set duration and controls separately after opening the prefilled prompt.

Set the input fields

Field	Required	Values and meaning
`model`	Yes	Top-level `elevenlabs/sound-effects-v2`
`input.prompt`	Yes	1–450 characters describing source, material, action, and space
`input.duration_seconds`	Yes	0.5–22 seconds; fractional values allowed; send explicitly
`input.prompt_influence`	No	0–1, default 0.3
`input.loop`	No	Boolean, default false

One request returns one 44.1 kHz, 128 kbps MP3. loop aims for a smooth head-to-tail join; it does not extend the clip. Repeat long background beds in the player.

curl: submit an effect

Running this example creates a real task billed by duration. Keep the key in the server environment variable HIAPI_API_KEY. Reuse the idempotency key for retries of the same request; use a new key for a new effect.

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
  }
}'

Read data.taskId from the create response, then query GET /v1/tasks/<taskId>.

Python: submit, wait, and save

Install requests before running this example. Only success and fail are terminal states; keep waiting during queued, handling, or 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}")

Three checks before integration

Failure and timeout. Check the HTTP status and task error. After the example's wait timeout, keep the taskId and resume querying instead of submitting a duplicate.
Input errors. For 400 INVALID_REQUEST, check the required duration, numeric ranges, and field types. Do not retry unchanged invalid input. Failed tasks refund the reserved charge.
Save the result. Download the audio URL after success. For batches, configure callback.url to receive terminal-state notifications.