API ElevenLabs Sound Effects v2: generare e scaricare effetti sonori

TL;DR

• ElevenLabs Sound Effects v2 converte una descrizione testuale in un effetto sonoro MP3; apri la pagina del modello per ascoltare esempi esistenti.
• La fatturazione si basa sulla durata richiesta, $0.0029 al secondo; 2 secondi costano $0.0058; il prezzo è stato verificato il 25 ottobre 2026, controlla il prezzo.
• Invia l'attività tramite l'interfaccia HiAPI /v1/tasks per ottenere un taskId, poi interroga il risultato.

Prima di eseguire l'esempio Python, esegui python -m pip install requests nello stesso ambiente Python.

Ascolta prima un esempio di due secondi

Questo è un caso di impatto a bassa frequenza dal taglio cinematografico già presente nella pagina del modello; di seguito sono riportati il suo prompt completo e l'audio.

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

Ascolta l'effetto sonoro completo

Genera con questo prompt →

elevenlabs/sound-effects-v2, 2 secondi, prompt_influence: 0.3, loop: false, MP3, al prezzo attuale di $0.0058. Dopo aver aperto il link precompilato, imposta separatamente la durata e i controlli.

Come compilare i parametri

Campo	Obbligatorio	Valori e descrizione
model	Sì	elevenlabs/sound-effects-v2, a livello superiore del corpo della richiesta
input.prompt	Sì	Da 1 a 450 caratteri, descrive suono, materiale, azione e spazio
input.duration_seconds	Sì	Da 0,5 a 22 secondi, supporta decimali; deve essere specificato esplicitamente
input.prompt_influence	No	Da 0 a 1, predefinito 0,3
input.loop	No	Valore booleano, predefinito false

Restituisce un MP3 a 44,1 kHz e 128 kbps per volta. loop serve a far combaciare il più possibile inizio e fine, non allunga l'audio; i suoni di sottofondo lunghi vengono ripetuti in loop dal riproduttore.

curl: invia il primo effetto sonoro

L'esecuzione dell'esempio crea un'attività reale e la fatturazione avviene in base alla durata. Inserisci la chiave nella variabile d'ambiente del server HIAPI_API_KEY. I tentativi ripetuti della stessa richiesta aziendale riutilizzano la chiave di idempotenza; le nuove richieste di effetti sonori usano una nuova chiave.

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

Ottieni l'ID attività da data.taskId nella risposta di creazione, poi interroga GET /v1/tasks/<taskId>.

Python: invio, attesa e salvataggio

Dopo aver installato requests, esegui l'esempio seguente. Considera come stati finali solo success e fail; queued, handling e archiving richiedono di continuare ad attendere.

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

Tre controlli prima della messa in produzione

1. Errori e timeout. Controlla lo stato HTTP e l'errore dell'attività; dopo il timeout di attesa, l'esempio conserva il taskId per continuare le interrogazioni successive ed evitare invii duplicati.
2. Parametri errati. In caso di 400 INVALID_REQUEST, verifica la durata obbligatoria, l'intervallo numerico e i tipi dei campi; non riprovare identico. L'addebito anticipato delle attività fallite viene rimborsato.
3. Salvataggio dei risultati. Dopo il successo, leggi l'URL audio e salvalo tempestivamente. Per le attività in batch puoi anche configurare callback.url per ricevere notifiche di stato finale.

Domande frequenti

Quanto può essere lungo l'effetto sonoro generato?

Ogni volta da 0,5 a 22 secondi, supporta secondi decimali, duration_seconds è obbligatorio.

loop allunga automaticamente l'effetto sonoro?

No. Serve a migliorare la continuità tra inizio e fine; la durata resta determinata da duration_seconds.

Quanto costa un effetto sonoro di due secondi?

Calcolando $0.0029 al secondo, due secondi costano $0.0058; le attività fallite rimborsano l'addebito anticipato.

Quando è possibile scaricare l'audio?

Attendi che status sia success, poi leggi la voce con type uguale a audio in output; durante la fase archiving continua ad attendere.

Continua l'integrazione

• Documentazione completa del modello
• Stato delle attività e callback
• Risoluzione degli errori della chiave
• Copia il prompt dell'esempio e crea l'effetto sonoro nella pagina del modello