ElevenLabs Music v2.5 API

ElevenLabs Music v2.5 API

ElevenLabs Music v2.5 пишет музыку по текстовому описанию: песни с вокалом и инструментальные треки. Вы описываете жанр, настроение, темп, инструменты и голос, при желании добавляете текст песни, задаёте длину в секундах и получаете MP3. Подходит для фоновой музыки к роликам и подкастам, джинглов, заставок и песен на заказ, в том числе на русском.

Что важно понимать заранее:

• длину трека вы задаёте сами, от 3 секунд до 10 минут;
• платите за каждую начатую минуту трека: до 60 секунд - 100 ₽;
• вокал появится, если его попросить в описании или дать текст песни; force_instrumental: true гарантирует трек без голоса.

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

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

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

Сценарии использования:

• Песня с вокалом - описание звучания плюс текст песни в том же prompt.
• Инструментальный трек - только описание и force_instrumental: true.

Это один и тот же вызов, сценарии отличаются значениями полей.

Тело запроса

{
  "tool": "elevenlabs-music-v2-5",
  "input": {
    "prompt": "...",
    "music_length_seconds": 60,
    "output_format": "mp3_48000_192"
  }
}

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

Параметры

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

Песня с вокалом на русском

Минутная песня: описание звучания и текст куплета с припевом в одном prompt.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "elevenlabs-music-v2-5",
  "input": {
    "prompt": "Инди-поп, тёплый женский вокал на русском языке, акустическая гитара, лёгкие барабаны, 100 BPM.\n\nТекст:\n[Verse]\nСемь утра, и город весь в снегу,\nМарина пьёт свой кофе на бегу.\n\n[Chorus]\nА ты скажи мне, что зима пройдёт,\nЧто март уже стоит за поворотом.",
    "music_length_seconds": 60,
    "force_instrumental": false,
    "output_format": "mp3_48000_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-music-v2-5',
    input: {
      prompt:
        'Инди-поп, тёплый женский вокал на русском языке, акустическая гитара, лёгкие барабаны, 100 BPM.\n\nТекст:\n[Verse]\nСемь утра, и город весь в снегу,\nМарина пьёт свой кофе на бегу.\n\n[Chorus]\nА ты скажи мне, что зима пройдёт,\nЧто март уже стоит за поворотом.',
      music_length_seconds: 60,
      force_instrumental: false,
      output_format: 'mp3_48000_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-music-v2-5',
        'input': {
            'prompt': (
                'Инди-поп, тёплый женский вокал на русском языке, акустическая гитара, '
                'лёгкие барабаны, 100 BPM.\n\nТекст:\n[Verse]\nСемь утра, и город весь в снегу,\n'
                'Марина пьёт свой кофе на бегу.\n\n[Chorus]\nА ты скажи мне, что зима пройдёт,\n'
                'Что март уже стоит за поворотом.'
            ),
            'music_length_seconds': 60,
            'force_instrumental': False,
            'output_format': 'mp3_48000_192',
        },
    },
    timeout=30,
)

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

Инструментальный фон

Двухминутная подложка без голоса для подкаста. Трек длиной 120 секунд стоит 200 ₽: две начатые минуты.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "elevenlabs-music-v2-5",
  "input": {
    "prompt": "Dark cinematic underscore: low cello drone, sparse soft piano notes, slow heartbeat-like pulse, 70 BPM, quiet and tense, leaves room for a narrator voice.",
    "music_length_seconds": 120,
    "force_instrumental": true,
    "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-music-v2-5',
    input: {
      prompt:
        'Dark cinematic underscore: low cello drone, sparse soft piano notes, slow heartbeat-like pulse, 70 BPM, quiet and tense, leaves room for a narrator voice.',
      music_length_seconds: 120,
      force_instrumental: true,
      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-music-v2-5',
        'input': {
            'prompt': (
                'Dark cinematic underscore: low cello drone, sparse soft piano notes, '
                'slow heartbeat-like pulse, 70 BPM, quiet and tense, leaves room for a narrator voice.'
            ),
            'music_length_seconds': 120,
            'force_instrumental': True,
            'output_format': 'mp3_44100_128',
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "elevenlabs-music-v2-5",
  "cost": 100,
  "balance_after": 400,
  "created_at": "2026-09-30T21:31:00.870676+00:00"
}

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

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "elevenlabs-music-v2-5",
  "cost": 100,
  "created_at": "2026-09-30T21:31:00.870676+00:00",
  "completed_at": "2026-09-30T21:31:28.682865+00:00",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.bratuha.ru/results/elevenlabs-music-v2-5/track-1.mp3"
    ],
    "files": [
      {
        "url": "https://storage.bratuha.ru/results/elevenlabs-music-v2-5/track-1.mp3",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Пока трек генерируется, status будет queued или processing, а result - null. При ошибке придёт status: "failed", result: null и текст причины в error_message, списанная сумма вернётся на баланс.

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

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

GET /api/v1/operations/{id}

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

Пример ожидания результата на JavaScript / TypeScript:

async function waitForTrack(id: string): Promise<string> {
  while (true) {
    const res = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const op = await res.json()
    if (op.status === 'completed') return op.result.urls[0]
    if (op.status === 'failed') throw new Error(op.error_message)
    await new Promise((r) => setTimeout(r, 5000))
  }
}

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

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

Короткие треки (до минуты) обычно готовы за 15-30 секунд, длинные генерируются дольше. Одну операцию можно опрашивать не чаще раза в секунду, иначе придёт 429. Проверки раз в 5 секунд хватает.

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

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

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

Файл стерео, с частотой и битрейтом из output_format. Длина совпадает с music_length_seconds с точностью до долей секунды: запрос на 3 секунды в формате mp3_22050_32 вернул файл 3,06 с, 22,05 кГц, 32 кбит/с.

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

Цена - 100 ₽ за каждую начатую минуту трека. Длина music_length_seconds делится на 60 и округляется вверх.

Описание, текст песни, force_instrumental и output_format на цену не влияют. Трек на 61 секунду стоит вдвое дороже трека на 60 секунд, поэтому для коротких роликов выбирайте длину, кратную минуте, или чуть меньше.

Сумма списывается при создании операции и приходит в поле cost.

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

• POST /api/v1/operations не идемпотентен: каждый запрос создаёт новую операцию и списывает деньги. Не повторяйте запрос автоматически при обрыве связи.
• Операция асинхронная: сначала приходит queued, результат забирайте через GET /api/v1/operations/{id}.
• music_length_seconds принимает только целые числа от 3 до 600. Дробное значение или число вне диапазона API отклонит с 400 validation_error, деньги не спишутся.
• Входных файлов у нейросети нет, все параметры передаются текстом.
• Текст песни пишите прямо в prompt после описания звучания. Разметка [Verse], [Chorus], [Bridge] помогает выстроить структуру. Следите, чтобы текст помещался в выбранную длину трека.
• Для русского вокала прямо укажите язык в описании («вокал на русском языке») и проверьте текст на опечатки заранее.
• Если нужен трек без голоса, передавайте force_instrumental: true, а не просто «без вокала» в описании.
• Есть предыдущая версия модели - elevenlabs-music-v2 с теми же параметрами и ценами.