ElevenLabs Sound Effect V2 API

ElevenLabs Sound Effect V2 API

ElevenLabs Sound Effect V2 делает короткие звуковые эффекты по текстовому описанию: шаги, дождь, скрип двери, взрыв, шум толпы, переходы для видео и фоновые атмосферы. Такой звук удобно подставлять в ролики, игры, презентации и приложения, когда нужного эффекта нет в библиотеке.

Что можно задать:

• описание звука - главное, от него зависит результат;
• длительность от 0,5 до 22 секунд;
• зацикливание, чтобы эффект можно было крутить по кругу без щелчка на стыке;
• насколько строго модель следует описанию;
• формат файла: MP3, PCM, μ-law, A-law или Opus.

Каждый вызов создаёт асинхронную операцию: сначала вы получаете id, затем проверяете статус, пока не придёт готовый файл.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос сразу возвращает id и стартовый статус queued.

Сценарии:

• Разовый эффект - описание, длительность и формат.
• Зацикленный фон - то же самое с loop: true, например для фоновой атмосферы в игре.

Тело запроса

{
  "tool": "elevenlabs-sound-effect-v2",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети, всегда "elevenlabs-sound-effect-v2".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, без дополнительной вложенности.

Параметры

Варианты output_format:

Формат на цену не влияет.

Примеры запросов

Разовый эффект

Пятисекундный звук дождя в MP3. Стоимость - 4 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "elevenlabs-sound-effect-v2",
  "input": {
    "text": "Heavy rain on a tin roof with distant thunder",
    "duration_seconds": 5,
    "output_format": "mp3_44100_128"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'elevenlabs-sound-effect-v2',
    input: {
      text: 'Heavy rain on a tin roof with distant thunder',
      duration_seconds: 5,
      output_format: 'mp3_44100_128',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'elevenlabs-sound-effect-v2',
        'input': {
            'text': 'Heavy rain on a tin roof with distant thunder',
            'duration_seconds': 5,
            'output_format': 'mp3_44100_128',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Зацикленный фон

Десять секунд лесной атмосферы, которую можно крутить по кругу. prompt_influence поднят до 0.6, чтобы звук точнее соответствовал описанию. Стоимость - 6,5 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "elevenlabs-sound-effect-v2",
  "input": {
    "text": "Calm forest ambience, birds chirping, light wind in the leaves",
    "duration_seconds": 10,
    "loop": true,
    "prompt_influence": 0.6,
    "output_format": "mp3_44100_192"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'elevenlabs-sound-effect-v2',
    input: {
      text: 'Calm forest ambience, birds chirping, light wind in the leaves',
      duration_seconds: 10,
      loop: true,
      prompt_influence: 0.6,
      output_format: 'mp3_44100_192',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'elevenlabs-sound-effect-v2',
        'input': {
            'text': 'Calm forest ambience, birds chirping, light wind in the leaves',
            'duration_seconds': 10,
            'loop': True,
            'prompt_influence': 0.6,
            'output_format': 'mp3_44100_192',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "elevenlabs-sound-effect-v2",
  "cost": 4,
  "balance_after": 496,
  "created_at": "2026-09-30T12:46:26Z"
}

• cost - сколько списано за операцию, в рублях.
• balance_after - баланс после списания.

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "elevenlabs-sound-effect-v2",
  "cost": 4,
  "created_at": "2026-09-30T12:46:26Z",
  "completed_at": "2026-09-30T12:46:38Z",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.bratuha.ru/results/elevenlabs-sound-effect-v2/sound-1.mp3"
    ],
    "files": [
      {
        "url": "https://storage.bratuha.ru/results/elevenlabs-sound-effect-v2/sound-1.mp3",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Ответ при ошибке

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "elevenlabs-sound-effect-v2",
  "cost": 4,
  "created_at": "2026-09-30T12:46:26Z",
  "completed_at": "2026-09-30T12:46:40Z",
  "result": null,
  "error_message": "Текст ошибки"
}

Проверка статуса

Сохраните id из ответа на создание и запрашивайте статус операции по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForResult(id) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 3000))
  }
}

Статус операции:

• queued - операция создана и ждёт запуска;
• processing - звук генерируется;
• completed - готово, ссылка лежит в result;
• failed - не получилось, причина в error_message.

Обычно эффект готов за 10-20 секунд. Опрашивать одну операцию можно не чаще раза в секунду, иначе придёт 429.

Формат результата

После завершения в result приходит один аудиофайл:

{
  "type": "audio",
  "urls": [
    "https://storage.bratuha.ru/results/elevenlabs-sound-effect-v2/sound-1.mp3"
  ],
  "files": [
    {
      "url": "https://storage.bratuha.ru/results/elevenlabs-sound-effect-v2/sound-1.mp3",
      "name": "result"
    }
  ]
}

• type - всегда "audio".
• urls - массив из одной ссылки на готовый файл.
• files - та же ссылка в виде объекта с url и name. Можно брать ссылку из любого из двух полей.

Длительность файла совпадает с duration_seconds: в тестовом запуске на 2 секунды пришёл MP3 длиной ровно 2,0 секунды, 44,1 кГц.

Ценообразование

Цена складывается из двух частей:

• 1,5 ₽ за каждый запуск;
• 0,5 ₽ за каждую секунду duration_seconds.

Дробные секунды считаются как есть, без округления: 3,4 секунды стоят 1,5 + 1,7 = 3,2 ₽.

Формат файла, loop и prompt_influence на цену не влияют. Точная сумма приходит в поле cost ответа на создание операции и сразу списывается с баланса.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый запрос создаёт новую операцию и списывает деньги. Не повторяйте запрос автоматически при обрыве связи: повтор создаст вторую оплаченную операцию.
• Операция выполняется асинхронно: сначала приходит queued, результат нужно забирать запросом статуса по id.
• Описание лучше писать на английском. Русский текст модель тоже принимает, но понимает хуже, и звук может получиться не тем.
• Одна генерация - один звук. Нужно несколько вариантов - создайте несколько операций.
• Модель делает шумы, эффекты и атмосферы, а не озвучку текста. Чтобы прочитать текст голосом, берите нейросети озвучки.
• Для длинного фона сделайте эффект на 10-22 секунды с loop: true и повторяйте его в своём плеере.
• pcm_* - это «сырой» звук без заголовка файла, обычный плеер его не откроет. Такие форматы нужны, если вы сами обрабатываете звук в коде. Для публикации и прослушивания выбирайте MP3 или Opus.
• Входных файлов у нейросети нет, все параметры передаются текстом и числами.