ElevenLabs Music API на HiAPI: генерация музыки с помощью curl, Python и рецептов промптов

Почему стоит вызывать elevenlabs/music-v2.5 через HiAPI

Если вы хотите добавить в продукт функцию генерации музыки, самый быстрый путь обычно не самый чистый. Прямое подключение бэкенда к провайдеру модели означает, что вы сами отвечаете за настройку аккаунта провайдера, схему аутентификации, семантику повторов и структуру запросов. Каждая новая модель добавляет новый набор таких решений, а каждый эксперимент оставляет ответвление интеграции.

Вызов elevenlabs/music-v2.5 через HiAPI меняет форму этой работы. Вам нужен только базовый URL, заголовок аутентификации и единый контракт запроса, который остаётся стабильным при переключении между моделями. Идентификатор модели (elevenlabs/music-v2.5) — это просто строка в теле запроса, поэтому переключение между музыкальными моделями или сравнение со второй моделью требует изменения одной строки, а не импорта нового SDK.

Для разработчиков, выбирающих способ интеграции, стоит выделить три практических преимущества:

• Единая поверхность управления учётными данными. Управление ключами, ротация и изоляция окружений (разработка/стейджинг/продакшн) сосредоточены в одном месте, а не умножаются на каждого провайдера.
• Переносимый шаблон запросов. Фрагменты кода на curl и Python ниже совпадают с тем, что вы используете для других моделей на HiAPI. Достаточно один раз изучить шаблон.
• Использование сосредоточено в одном месте. Генерация музыки тарифицируется по длительности вывода; объединение её с использованием других моделей означает отслеживание затрат в единой панели, а не разрозненные счета.

Цена — это слой абстракции, поэтому специфические особенности провайдера нормализуются. Для первой интеграции и большинства производственных сценариев такая нормализация — именно то, что нужно. Когда вам нужно понять конкретное поведение модели, страница с подробностями на сайте является авторитетным источником.

Подготовка перед первым музыкальным запросом

Перед написанием кода убедитесь в четырёх вещах, чтобы первый вызов вернул аудио, а не 401 или ошибку валидации.

1. API-ключ

Вам нужен API-ключ из вашей учётной записи HiAPI. Обращайтесь с ним как с любым другим секретом: храните в переменной окружения, никогда не коммитьте в исходный код и используйте разные ключи для локальной разработки и продакшна, чтобы можно было отозвать один, не затрагивая другой.

export HIAPI_API_KEY="your_key_here"

2. Базовый URL и контракт эндпоинта

Все вызовы моделей идут через один базовый URL, а модель идентифицируется внутри запроса, а не в пути. Храните константу базового URL в проекте, чтобы при изменении окружения менять только одно место.

3. Промпт на естественном языке

elevenlabs/music-v2.5 принимает текстовый промпт, описывающий желаемую музыку. Вам не нужны ноты или MIDI-файлы. Одного-двух предложений, указывающих жанр, инструментовку, настроение и предполагаемую длительность, достаточно для начала. В последующих разделах приведены многоразовые рецепты.

4. Правильные ожидания от вывода

Генерация музыки возвращает аудио, а не JSON-партитуру. Заранее спланируйте обработку ответа: запись в файл при разработке, потоковая передача или хранение в продакшне. Заранее решите, какой примерно длины должен быть фрагмент, поскольку длительность влияет как на запрос, так и на тарификацию.

Ещё одна вещь перед первым запросом: посмотрите текущие ограничения скорости и цену elevenlabs/music-v2.5 на панели тарифов сайта, а не закладывайте предположения в код. Цены и лимиты меняются, ваша интеграция должна читать их как конфигурацию, а не встраивать как константы скрипта.

Первый вызов через curl

Начните с curl, потому что он убирает все слои между вами и HTTP-запросом. Если вызов curl успешен, то любая ошибка в приложении — это проблема приложения, а не API.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

Что делает каждая часть:

• -sS подавляет вывод прогресса, но всё равно показывает ошибки. Полезно, когда вы перенаправляете вывод в файл.
• URL — это единый эндпоинт. Обратите внимание, что имя модели не появляется в пути, а находится в теле запроса.
• Authorization: Bearer $HIAPI_API_KEY читает ключ из окружения, чтобы он не оставался в истории shell в открытом виде. В Windows задайте переменную с помощью set или синтаксиса PowerShell $env:.
• Content-Type: application/json обязателен; эндпоинт не принимает form-encoding.
• model — это точный идентификатор elevenlabs/music-v2.5. Опечатка здесь даёт ошибку «модель не найдена», а не общий сбой, что полезно для отладки.
• messages передаёт ваш промпт как содержимое пользовательского сообщения. Поместите промпт в одно сообщение; длинные структурированные промпты работают лучше, чем разбитые на несколько.

Тело ответа содержит сгенерированное аудио и метаданные о запросе. При разработке перенаправляйте вывод в файл, чтобы сразу прослушать результат:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

Помещение полезной нагрузки в request.json и чтение через -d @request.json — это привычка, которую стоит выработать как можно раньше. Она делает запросы сравнимыми, проверяемыми и легко воспроизводимыми при изменении одного параметра за раз.

Повторение вызова на Python

Как только вызов curl возвращает аудио, перенесите его на Python. Цель — не просто рабочий скрипт, а функция, которую можно вызывать из очереди задач, обработчика API или ноутбука без расхождений из-за копирования и вставки.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """Отправляет музыкальный промпт в elevenlabs/music-v2.5 через HiAPI."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

По мере роста функции есть несколько решений, которые стоит сохранить:

• Предпочитайте стандартную библиотеку. urllib избавляет руководство от изменчивости зависимостей. Если ваш проект уже использует requests или httpx, преобразование механическое: передайте json=payload, headers=headers и timeout.
• Таймаут обязателен. Генерация музыки занимает больше времени, чем чат-дополнения. Задайте явный таймаут, не полагайтесь на значения по умолчанию. Выберите значение больше ожидаемого времени генерации самого длинного фрагмента, который вы запрашиваете.
• Читайте ключ во время вызова, а не при импорте, чтобы один и тот же модуль работал локально и в контейнере, куда окружение внедряется во время выполнения.
• Возвращайте структурированные данные, а не печатайте строку. Вызывающая сторона решает, записывать аудио на диск, загружать в объектное хранилище или пересылать клиенту.

Перед тем как что-либо строить на их основе, убедитесь, что функция Python и вызов curl дают эквивалентные результаты для одного и того же промпта. Это соответствие — ваша базовая линия регрессии.

Рецепты промптов для стиля, настроения и длительности

Музыкальные промпты работают лучше всего, когда последовательно отвечают на три вопроса: какой жанр и инструментовка, какая эмоциональная тональность, как долго. Расплывчатые промпты дают обобщённый результат; слишком длинные промпты размывают важные описательные слова. Цель — одно плотное предложение или три коротких фразы.

Используйте их как готовые к копированию отправные точки и меняйте только одно измерение за раз.

Рецепты с доминированием стиля

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

Рецепты с доминированием настроения

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

Рецепты с доминированием длительности

Длительность следует указывать в промпте как явную цель, и она должна соответствовать аранжировке. Запрос на 15 секунд с медленным нарастанием и длинным хвостом будет резко обрезан.

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

Комбинированный пример

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

Когда вывод не соответствует ожиданиям

Меняйте только одну переменную за попытку, чтобы понимать, что именно изменило результат.

• Слишком обобщённо: замените слова настроения конкретной инструментовкой и темпом. «Energetic» слабее, чем «driving 16th-note bass at 128 BPM».
• Слишком насыщенно или хаотично: явно уберите инструменты (no drums, no vocals, sparse arrangement), а не добавляйте больше положительных описателей.
• Длина кажется неправильной: если фрагмент резко обрывается, запросите более короткую цель с явным окончанием; если кажется поспешным, уменьшите количество запрошенных секций.
• Дрейф стиля: переместите жанр и инструментовку в начало промпта. Токены в начале имеют больший вес.

Храните в репозитории небольшой файл промптов с записями рабочих рецептов. Этот файл ценнее любого отдельного сгенерированного фрагмента, потому что превращает написание промптов в воспроизводимый инженерный артефакт.

Распространённые ошибки и способы их исправления

Большинство первых интеграций терпят неудачу предсказуемыми способами. Прежде чем начинать гадать, пройдитесь по этому списку.

Ошибки аутентификации

401 почти всегда означает неправильный формат заголовка или отсутствие ключа в окружении процесса. Проверьте, нет ли лишних пробелов после Bearer, не загружен ли ключ из неверного файла .env, или не выполнен ли export в другой сессии, чем запуск скрипта. Выведите длину ключа (не сам ключ), чтобы убедиться, что он заполнен.

Несовпадение идентификатора модели

Ошибка «модель не найдена» или ошибка валидации обычно означает, что строка model не является точным совпадением. elevenlabs/music-v2.5 чувствителен к регистру и содержит косую черту. Если вы скопировали его из окна чата, проверьте наличие «умных» кавычек или остатков переноса строки.

Неправильный формат тела запроса

Если curl работает, а Python — нет, разница почти всегда в сериализации. Передача Python dict туда, где ожидается JSON-строка, двойное кодирование через json.dumps или забытый Content-Type: application/json приводят к ошибке парсинга на сервере, которая выглядит не связанной с реальной причиной. Залогируйте точное тело запроса, отправляемое кодом, и сравните его с рабочим curl-запросом посимвольно.

Таймауты на более длинных фрагментах

Более длинная длительность требует больше времени генерации. Клиентский таймаут, подходящий для чат-запроса, обрежет более длинные музыкальные запросы. Увеличьте таймаут специально для этого эндпоинта и добавляйте повтор с экспоненциальной задержкой только для сбоев на уровне соединения, никогда не повторяйте слепо запрос, который мог уже быть тарифицирован.

Длина и содержание промпта

Чрезмерно длинные промпты или промпты, содержащие инструкции о самом API, часто дают худшую музыку. Пусть промпт будет только о музыке. Если промпт, работавший вчера, перестал работать, упростите его до каркаса стиль/настроение/длительность, а затем наращивайте заново.

Обработка ответа как текста

Эндпоинт возвращает аудиоданные, а не читаемую транскрипцию. Запись сырого тела ответа в файл .txt и последующее недоумение, почему он не воспроизводится, — распространённая ошибка первого дня. Сохраняйте с правильным аудиорасширением и проверяйте, что файл открывается в плеере, прежде чем строить дальше.

Когда ошибка действительно неясна, воспроизведите её с минимально возможным curl-запросом. Это изолирует, проблема в контракте API или в вашем коде.

От тестового вызова к воспроизводимому рабочему процессу

Успешный тестовый вызов — это отправная точка, а не интеграция. Используйте этот список, чтобы превратить его в то, на что команда может положиться.

• Вынесите конфигурацию наружу. Базовый URL, идентификатор модели, таймауты и целевые значения длительности по умолчанию — в конфигурацию, а не в разбросанные строковые литералы. Значения, зависящие от окружения, берутся из окружения.
• Централизуйте клиент. Одна функция или лёгкий клиентский класс отвечает за запрос. Ни один модуль не должен самостоятельно строить HTTP-вызовы к музыкальному эндпоинту, иначе вы разойдётесь в заголовках и обработке ошибок.
• Обрабатывайте ошибки по категориям. Различайте аутентификацию, валидацию, таймауты и ошибки сервера. Повторяйте только временные ошибки, с задержкой и верхним пределом. Никогда не повторяйте запрос, который мог уже создать вывод и быть тарифицирован.
• Правильно храните аудио. Записывайте в объектное хранилище с детерминированными ключами, храните промпт вместе со сгенерированным активом и записывайте идентификатор модели. Воспроизведение результатов позже зависит от точного знания того, что было запрошено.
• Отслеживайте длительность как первоклассный параметр. Поскольку тарификация следует за длительностью вывода, указывайте целевую длительность в шаблонах промптов и записывайте её для каждого запроса, чтобы отчёты о затратах соответствовали использованию.
• Создайте библиотеку промптов. Держите проверенные рецепты под контролем версий с короткой пометкой о назначении каждого. Новые члены команды начинают с рабочих промптов, а не с догадок.
• Разделяйте синхронный и асинхронный пути. Генерация может быть медленной. Для пользовательских функций отправляйте задание, сохраняйте запрос и позволяйте воркеру вызывать модель. HTTP-обработчик не должен оставаться открытым на всё время генерации.
• Проверяйте дымовым тестом. Тест, который отправляет фиксированный короткий промпт и утверждает, что аудиоответ имеет правильный формат, рано выявляет дрейф учётных данных и контракта.

Когда вы будете готовы глубже изучить параметры и ограничения, страница модели elevenlabs/music-v2.5 на HiAPI — это место, где смотрят текущие возможности перед тем, как закладывать предположения в код.