API ElevenLabs Sound Effects v2 : générer et télécharger des effets sonores

TL;DR

• ElevenLabs Sound Effects v2 transforme une description textuelle en un effet sonore MP3 ; ouvrez la page du modèle pour écouter des exemples existants.
• La facturation dépend de la durée demandée, soit 0,0029 $ par seconde ; 2 secondes coûtent 0,0058 $. Le prix a été vérifié le 25 octobre 2026, voir les tarifs.
• Soumettez une tâche via l'API HiAPI /v1/tasks pour obtenir un taskId, puis interrogez le résultat.

Avant d'exécuter l'exemple Python, lancez python -m pip install requests dans le même environnement Python.

Écoutez d'abord un exemple de deux secondes

Voici l'exemple d'impact grave cinématographique déjà présent sur la page du modèle ; son prompt complet et l'audio sont conservés ci-dessous.

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

Écouter l'effet sonore complet

Générer avec ce prompt →

elevenlabs/sound-effects-v2, 2 secondes, prompt_influence: 0.3, loop: false, MP3, au tarif actuel de 0,0058 $. Après avoir ouvert le lien prérempli, définissez séparément la durée et les options de contrôle.

Comment remplir les paramètres

Champ	Obligatoire	Valeurs et description
model	Oui	elevenlabs/sound-effects-v2, au niveau supérieur du corps de la requête
input.prompt	Oui	1 à 450 caractères, décrivant le son, la matière, l'action et l'espace
input.duration_seconds	Oui	0,5 à 22 secondes, les décimales sont acceptées ; doit être renseigné explicitement
input.prompt_influence	Non	0 à 1, valeur par défaut 0,3
input.loop	Non	Booléen, valeur par défaut false

Chaque appel renvoie un MP3 à 44,1 kHz et 128 kbps. loop sert à améliorer l'enchaînement entre le début et la fin ; il n'allonge pas l'audio. Les longues ambiances sont bouclées par le lecteur.

curl : soumettre son premier effet sonore

L'exécution de cet exemple crée une vraie tâche facturée selon la durée. Placez la clé dans la variable d'environnement du serveur HIAPI_API_KEY. Réutilisez la même clé d'idempotence pour les nouvelles tentatives d'une même requête métier ; utilisez une nouvelle clé pour chaque nouvelle demande d'effet sonore.

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

Récupérez l'ID de tâche dans data.taskId de la réponse de création, puis interrogez GET /v1/tasks/<taskId>.

Python : soumettre, attendre et enregistrer

Après avoir installé requests, exécutez l'exemple ci-dessous. Ne considérez que success et fail comme des états finaux ; queued, handling et archiving nécessitent de continuer à attendre.

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

Trois vérifications avant la mise en production

1. Échecs et délais d'attente. Vérifiez le statut HTTP et l'erreur de la tâche ; en cas de dépassement du délai d'attente, l'exemple conserve le taskId et continue à l'interroger ensuite, afin d'éviter une resoumission en double.
2. Erreurs de paramètres. En cas de 400 INVALID_REQUEST, vérifiez la durée obligatoire, les plages de valeurs et les types de champs ; ne réessayez pas à l'identique. Les montants prélevés pour les tâches échouées sont remboursés.
3. Enregistrement du résultat. En cas de succès, lisez l'URL de l'audio et enregistrez-la rapidement. Pour les tâches par lots, vous pouvez aussi configurer callback.url pour recevoir les notifications d'état final.

Questions fréquentes

Quelle durée d'effet sonore peut-on générer ?

De 0,5 à 22 secondes par appel, les secondes décimales sont acceptées, duration_seconds est obligatoire.

loop allonge-t-il automatiquement l'effet sonore ?

Non. Il améliore l'enchaînement entre le début et la fin, mais la durée reste déterminée par duration_seconds.

Combien coûte un effet sonore de deux secondes ?

À 0,0029 $ par seconde, deux secondes coûtent 0,0058 $ ; les tâches échouées donnent lieu au remboursement du montant prélevé.

Quand peut-on télécharger l'audio ?

Attendez que status soit success, puis lisez l'élément de type audio dans output ; pendant la phase archiving, continuez à attendre.

Aller plus loin

• Documentation complète du modèle
• États des tâches et callbacks
• Dépannage des erreurs de clé
• Copier le prompt de l'exemple et créer un effet sonore sur la page du modèle