ElevenLabs Sound Effects v2 API: Soundeffekte generieren und herunterladen

TL;DR

• ElevenLabs Sound Effects v2 wandelt eine Textbeschreibung in einen MP3-Soundeffekt um; öffnen Sie die Modellseite, um vorhandene Beispiele anzuhören.
• Die Abrechnung erfolgt nach der angeforderten Dauer, $0.0029 pro Sekunde; 2 Sekunden kosten $0.0058. Der Preis wurde am 25. Oktober 2026 überprüft, Preise ansehen.
• Reichen Sie die Aufgabe über die HiAPI-Schnittstelle /v1/tasks ein, um eine taskId zu erhalten, und fragen Sie dann das Ergebnis ab.

Bevor Sie das Python-Beispiel ausführen, führen Sie python -m pip install requests in derselben Python-Umgebung aus.

Hören Sie zuerst ein Zwei-Sekunden-Beispiel

Dies ist das bereits auf der Modellseite vorhandene filmische Beispiel mit tiefem Bassimpuls; der vollständige Prompt und das Audio sind unten erhalten.

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

Vollständigen Soundeffekt anhören

Mit diesem Prompt generieren →

elevenlabs/sound-effects-v2, 2 Sekunden, prompt_influence: 0.3, loop: false, MP3, zum aktuellen Preis von $0.0058. Nach dem Öffnen des vorausgefüllten Links stellen Sie zusätzlich die Dauer und die Steuerungsoptionen ein.

So füllen Sie die Parameter aus

Feld	Erforderlich	Werte und Beschreibung
model	Ja	elevenlabs/sound-effects-v2, auf oberster Ebene des Anforderungstexts angeben
input.prompt	Ja	1–450 Zeichen; beschreibt Klang, Material, Aktion und Raum
input.duration_seconds	Ja	0,5–22 Sekunden, Dezimalwerte unterstützt; muss explizit angegeben werden
input.prompt_influence	Nein	0–1, Standardwert 0,3
input.loop	Nein	Boolescher Wert, Standardwert false

Ein Aufruf liefert eine MP3 mit 44,1 kHz und 128 kbps zurück. loop dient dazu, Anfang und Ende möglichst nahtlos zu verbinden, und verlängert das Audio nicht; lange Hintergrundgeräusche werden auf der Wiedergabeseite in einer Schleife abgespielt.

curl: Ersten Soundeffekt übermitteln

Beim Ausführen des Beispiels wird eine echte Aufgabe erstellt und die Dauer abgerechnet. Legen Sie den Schlüssel in der Serverumgebungsvariable HIAPI_API_KEY ab. Bei Wiederholungen derselben Geschäftsanforderung wird derselbe Idempotenzschlüssel wiederverwendet; für neue Soundeffekt-Anforderungen verwenden Sie einen neuen Schlüssel.

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

Entnehmen Sie die Aufgaben-ID aus data.taskId der Erstellungsantwort und fragen Sie dann GET /v1/tasks/<taskId> ab.

Python: Übermitteln, warten und speichern

Installieren Sie requests und führen Sie dann das folgende Beispiel aus. Betrachten Sie nur success und fail als Endzustände; bei queued, handling und archiving müssen Sie weiter warten.

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}")

Drei Prüfungen vor dem Go-live

1. Fehler und Zeitüberschreitungen. Prüfen Sie den HTTP-Status und den Task-Error; das Beispiel behält die taskId nach einer Zeitüberschreitung, um später weiter abzufragen und doppelte Übermittlungen zu vermeiden.
2. Parameterfehler. Bei 400 INVALID_REQUEST prüfen Sie die erforderliche Dauer, Wertebereiche und Feldtypen; nicht unverändert erneut versuchen. Vorab reservierte Beträge fehlgeschlagener Aufgaben werden zurückerstattet.
3. Ergebnis speichern. Lesen Sie nach dem Erfolg die Audio-URL und speichern Sie sie zeitnah. Bei Batch-Aufgaben können Sie auch callback.url konfigurieren, um Benachrichtigungen über den Endzustand zu erhalten.

Häufige Fragen

Wie lange kann ein Soundeffekt sein?

Jeweils 0,5–22 Sekunden, Dezimalsekunden werden unterstützt, duration_seconds ist erforderlich.

Verlängert loop den Soundeffekt automatisch?

Nein. Es verbessert die Verbindung von Anfang und Ende; die Dauer wird weiterhin durch duration_seconds bestimmt.

Was kostet ein Zwei-Sekunden-Soundeffekt?

Bei $0.0029 pro Sekunde kosten zwei Sekunden $0.0058; bei fehlgeschlagenen Aufgaben wird der vorab reservierte Betrag zurückerstattet.

Wann kann das Audio heruntergeladen werden?

Warten Sie, bis status gleich success ist, und lesen Sie dann den Eintrag mit type gleich audio in output; während der Phase archiving warten Sie weiter.

Weiter integrieren

• Vollständige Modelldokumentation
• Aufgabenstatus und Callbacks
• Fehlerbehebung bei Schlüsselfehlern
• Beispiel-Prompt kopieren und auf der Modellseite Soundeffekte erstellen