ElevenLabs Sound Effects v2 API: генерация и скачивание звуковых эффектов

TL;DR

• ElevenLabs Sound Effects v2 превращает текстовое описание в один MP3-звук; откройте страницу модели, чтобы прослушать существующие примеры.
• Оплата зависит от запрошенной длительности: $0.0029 за секунду; 2 секунды стоят $0.0058. Цена проверена 25 октября 2026 года, посмотреть цены.
• Отправьте задачу через интерфейс HiAPI /v1/tasks, получите taskId, затем запросите результат.

Перед запуском примера на Python выполните в том же окружении Python команду python -m pip install requests.

Сначала послушайте двухсекундный пример

Это уже существующий на странице модели пример кинематографичного низкочастотного удара; ниже приведены его полный промпт и аудио.

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

Прослушать полный звуковой эффект

Сгенерировать с этим промптом →

elevenlabs/sound-effects-v2, 2 секунды, prompt_influence: 0.3, loop: false, MP3, по текущей цене $0.0058. После открытия предзаполненной ссылки дополнительно задайте длительность и параметры управления.

Как заполнять параметры

Поле	Обязательно	Значения и описание
model	Да	elevenlabs/sound-effects-v2, на верхнем уровне тела запроса
input.prompt	Да	1–450 символов, описывает звук, материалы, действие и пространство
input.duration_seconds	Да	0.5–22 секунды, поддерживаются дробные значения; необходимо указать явно
input.prompt_influence	Нет	0–1, по умолчанию 0.3
input.loop	Нет	Логическое значение, по умолчанию false

За один раз возвращается один MP3 44.1 кГц, 128 кбит/с. loop служит для максимального сглаживания стыка начала и конца и не удлиняет аудио; длительный фоновый звук зацикливается на стороне воспроизведения.

curl: отправка первого звукового эффекта

Запуск примера создаёт реальную задачу и оплачивается по длительности. Поместите ключ в серверную переменную окружения HIAPI_API_KEY. Для повторных запросов одного и того же бизнес-запроса используйте один и тот же ключ идемпотентности; для новых запросов звука используйте новый ключ.

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

Возьмите ID задачи из data.taskId ответа на создание, затем запросите GET /v1/tasks/<taskId>.

Python: отправка, ожидание и сохранение

Установите requests и запустите пример ниже. Считайте конечными только состояния success и fail; queued, handling, 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}")

Три проверки перед запуском в продакшен

1. Ошибки и тайм-ауты. Проверяйте HTTP-статус и ошибку задачи; в примере при тайм-ауте ожидания taskId сохраняется для последующих запросов, чтобы избежать повторной отправки.
2. Ошибки параметров. При 400 INVALID_REQUEST проверьте обязательную длительность, диапазоны значений и типы полей; не повторяйте запрос как есть. Предварительно удержанная сумма за неудачные задачи возвращается.
3. Сохранение результата. После успеха прочитайте URL аудио и своевременно сохраните его. Для пакетных задач также можно настроить callback.url для получения уведомлений о конечном состоянии.

Частые вопросы

Какой длины звуковой эффект можно сгенерировать?

Каждый раз от 0.5 до 22 секунд, поддерживаются дробные секунды, duration_seconds обязателен.

Автоматически ли loop удлиняет звуковой эффект?

Нет. Он служит для улучшения стыка начала и конца, длительность по-прежнему определяется duration_seconds.

Сколько стоит двухсекундный звуковой эффект?

Из расчёта $0.0029 за секунду две секунды стоят $0.0058; за неудачные задачи предварительно удержанная сумма возвращается.

Когда можно скачать аудио?

Дождитесь статуса success, затем прочитайте элемент с type audio в output; на этапе archiving продолжайте ожидание.

Продолжить интеграцию

• Полная документация модели
• Статусы задач и callback
• Диагностика ошибок ключа
• Скопируйте промпт примера и создайте звуковой эффект на странице модели