API ElevenLabs Sound Effects v2: generar y descargar efectos de sonido

TL;DR

• ElevenLabs Sound Effects v2 convierte una descripción de texto en un archivo MP3 de efecto de sonido; abre la página del modelo para escuchar casos existentes.
• Se factura según la duración solicitada, $0.0029 por segundo; 2 segundos cuestan $0.0058; el precio se verificó el 25 de octubre de 2026, consulta el precio.
• Envía la tarea mediante la interfaz de HiAPI /v1/tasks y obtén un taskId, luego consulta el resultado.

Antes de ejecutar el ejemplo de Python, ejecuta python -m pip install requests en el mismo entorno de Python.

Primero escucha un caso de dos segundos

Este es el caso de impacto cinematográfico de baja frecuencia que ya existe en la página del modelo; a continuación se conservan su prompt completo y el 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.

Escuchar el efecto de sonido completo

Generar con este prompt →

elevenlabs/sound-effects-v2, 2 segundos, prompt_influence: 0.3, loop: false, MP3, al precio actual de $0.0058. Después de abrir el enlace prellenado, configura la duración y los controles por separado.

Cómo rellenar los parámetros

Campo	Obligatorio	Valores y descripción
model	Sí	elevenlabs/sound-effects-v2, en el nivel superior del cuerpo de la solicitud
input.prompt	Sí	1–450 caracteres, describe el sonido, el material, la acción y el espacio
input.duration_seconds	Sí	0.5–22 segundos, admite decimales; debe indicarse explícitamente
input.prompt_influence	No	0–1, valor predeterminado 0.3
input.loop	No	Booleano, valor predeterminado false

Devuelve un MP3 a 44.1 kHz y 128 kbps por vez. loop sirve para que el inicio y el final se acoplen lo mejor posible; no alarga el audio; los sonidos de fondo largos se reproducen en bucle en el reproductor.

curl: enviar el primer efecto de sonido

Ejecutar el ejemplo crea una tarea real y se factura según la duración. Coloca la clave en la variable de entorno del servidor HIAPI_API_KEY. Los reintentos de la misma solicitud de negocio reutilizan la clave de idempotencia; las nuevas solicitudes de efectos de sonido usan una clave nueva.

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

Obtén el ID de la tarea desde data.taskId de la respuesta de creación y luego consulta GET /v1/tasks/<taskId>.

Python: enviar, esperar y guardar

Después de instalar requests, ejecuta el siguiente ejemplo. Solo considera success y fail como estados finales; queued, handling y archiving requieren seguir esperando.

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

Tres comprobaciones antes de publicar

1. Fallos y tiempos de espera. Revisa el estado HTTP y el error de la tarea; el ejemplo conserva el taskId tras agotar el tiempo de espera para seguir consultándolo después y evitar envíos duplicados.
2. Errores de parámetros. Si recibes 400 INVALID_REQUEST, revisa la duración obligatoria, los rangos numéricos y los tipos de campo; no reintentes tal cual. El cargo retenido de las tareas fallidas se reembolsa.
3. Guardado del resultado. Tras el éxito, lee la URL del audio y guárdalo a tiempo. Para tareas por lotes también puedes configurar callback.url para recibir la notificación del estado final.

Preguntas frecuentes

¿Qué duración puede tener el efecto de sonido generado?

Cada vez, de 0.5 a 22 segundos, admite segundos decimales; duration_seconds es obligatorio.

¿loop alarga automáticamente el efecto de sonido?

No. Sirve para mejorar la transición entre el inicio y el final; la duración sigue determinada por duration_seconds.

¿Cuánto cuesta un efecto de sonido de dos segundos?

Calculado a $0.0029 por segundo, dos segundos cuestan $0.0058; las tareas fallidas reembolsan el cargo retenido.

¿Cuándo se puede descargar el audio?

Espera a que status sea success y luego lee el elemento con type igual a audio en output; durante la fase archiving sigue esperando.

Continuar la integración

• Documentación completa del modelo
• Estado de tareas y callbacks
• Solución de errores de clave
• Copia el prompt del caso y ve a la página del modelo para crear un efecto de sonido