Руководство

Как использовать mureka-9.5/instrumental через HiAPI API: руководство по curl и Python

Nov 3, 2026

Возможности mureka-9.5/instrumental на HiAPI

mureka-9.5/instrumental — это эндпоинт текстовой генерации музыки на HiAPI, специально настроенный для чисто инструментального вывода: фоновая музыка, луп-фрагменты, подложка и саундтреки. Вы описываете трек в промпте, отправляете одну задачу, и HiAPI возвращает готовый аудиоресурс, который можно скачать и вставить в игру, видеомонтаж, подкаст или продуктовую демонстрацию.

Ключевое слово здесь — instrumental (инструментал). Эндпоинт ориентирован на музыку без вокального исполнения, поэтому подходит для сценариев, где закадровый голос или диалоги должны оставаться чёткими и разборчивыми. Если вам нужен вокальный трек с текстом — это другая задача; если вам нужна чистая фоновая музыка под озвучку — это правильный инструмент.

Выбирайте этот эндпоинт, когда:

Вы хотите генерировать фоновую музыку (BGM), а не брать её из музыкальной библиотеки.
Вам нужно быстро, программно генерировать множество вариантов, а не заказывать разовую авторскую работу.
Ваш пайплайн уже использует HTTP, и вы хотите обрабатывать музыку как любой другой шаг генерации ресурсов.
Вам важна предсказуемая форма запроса: отправка, опрос, скачивание.

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

Где это применяется в продукте

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

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

Подготовка перед отправкой запроса

Чтобы первый вызов прошёл успешно, нужно выполнить несколько условий. Ничего сложного, но пропуск любого из них — самая частая причина неудачи первого запроса.

Учётные данные

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

export HIAPI_API_KEY="your_api_key_here"

Эндпоинт и транспорт

Вы вызываете модель mureka-9.5/instrumental через единый API HiAPI. Базовый URL — хост HiAPI API; идентификатор модели размещается в теле запроса или в пути согласно принятому в HiAPI соглашению для этого эндпоинта. Используйте HTTPS, отправляйте Content-Type: application/json и JSON-тело.

Не угадывайте имена параметров. HiAPI документирует поля, которые принимает эта модель; всё, что вне этого набора, в лучшем случае игнорируется, в худшем — отклоняется. Если нужного поля нет в документации, оно не входит в контракт — стройте на том, что есть.

Что подготовить

Промпт, описывающий музыку: жанр, состав инструментов, настроение, ритмический рисунок и целевое назначение.
Документированные опции длительности или вариаций, которые публикует модель.
Место для хранения идентификатора задачи и, позже, URL для скачивания.
Сетевой доступ от места запуска кода до хоста HiAPI.

Замечание о времени

Генерация не мгновенна. Задайте клиентский таймаут свободнее и рассчитывайте на опрос. Синхронный подход — отправить запрос и ждать до возврата аудио в том же ответе — приводит к нестабильному коду.

Рабочий запрос curl

Начните с curl. Он убирает каждый слой между вами и HTTP, поэтому проблемы видны сразу.

Вызов

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "warm lo-fi hip hop instrumental, mellow electric piano, soft vinyl crackle, relaxed 80 bpm, no vocals"
    }
  }'

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

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # 使用该端点有文档记录的路径
export HIAPI_API_KEY="your_api_key_here"

Назначение частей

-X POST — отправка является операцией создания.
-H "Authorization: Bearer ..." — аутентифицирует вызов вашим аккаунтом.
-H "Content-Type: application/json" — сообщает серверу, что тело в формате JSON; без него многие серверы просто отклонят тело.
-d '{...}' — JSON-нагрузка. Поле model задаёт эндпоинт; объект input содержит промпт и другие документированные поля.
-sS — тихий прогресс, но с выводом ошибок. Удобно в скриптах.

Чтение ответа

Ответ — JSON. Ищите идентификатор задачи или задания и поле статуса. Отформатируйте красиво для проверки:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

Сохраните идентификатор. Это дескриптор для каждой последующей проверки статуса. Не парсите весь ответ в приложение; извлеките ID задачи и статус, а сырой ответ сохраните для отладки.

Если получен не-2xx статус, прочитайте тело — HiAPI возвращает структурированные сообщения об ошибках, обычно указывая проблемное поле.

Тот же запрос в Python

Версия на Python точно соответствует вызову curl: те же заголовки, то же JSON-тело. Для краткости используйте requests, либо стандартную библиотеку для нулевых зависимостей.

С использованием requests

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "warm lo-fi hip hop instrumental, mellow electric piano, "
            "soft vinyl crackle, relaxed 80 bpm, no vocals"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # use the documented field name
print("submitted:", job_id, data.get("status"))

С использованием стандартной библиотеки

Если добавить зависимость нельзя:

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

Полезные привычки

Используйте timeout=30 только при отправке. Опросу нужен собственный цикл и собственный таймаут.
Вызывайте raise_for_status() до парсинга. Тело ответа с ошибкой — это не задача.
Оберните извлечение ID задачи в небольшой вспомогательный метод, чтобы смена имени поля требовала правки в одной строке.
Никогда не логируйте API-ключ; вместо этого логируйте ID задачи и статус.
Держите нагрузку как словарь в коде, сериализуйте один раз, чтобы тесты могли проверять его.

Обработка асинхронных задач и опрос

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

Форма цикла

Отправить задачу, захватить ID.
Короткая пауза.
Запросить статус для этого ID.
Если статус — в очереди или обработке, выждать с backoff и повторить.
Если статус — успешный, прочитать вывод.
Если статус — ошибка, залогировать ошибку и остановиться — не повторять слепо.

Надёжная реализация

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # jitter
        delay = min(delay * 1.5, max_delay)          # exponential backoff

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

Почему важна каждая деталь

Дрожание (Jitter) предотвращает синхронные повторы при параллельной работе многих задач.
Откат (Backoff) предотвращает нагрузку на эндпоинт статуса, пока трек рендерится.
Дедлайн превращает бесконечное зависание в чистое исключение, обрабатываемое пайплайном.
Проверка терминальных состояний должна соответствовать задокументированным в HiAPI строкам статусов. Сверяйтесь со справочником API, а не полагайтесь на догадки.
Повторы должны применяться к временным сетевым ошибкам (таймауты, 5xx), а не к задаче, уже провалившейся из-за ошибки валидации.

Операционные советы

Сохраните job_id до начала опроса. Если процесс умрёт, вы сможете возобновить опрос, а не платить за вторую генерацию. Логируйте переходы состояний с временными метками, чтобы видеть, куда уходит время. Если задач много, опрашивайте параллельно небольшое их число через очередь, а не блокируйте по одному потоку запроса на задачу.

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

Инструментальный режим выражается в запросе — эндпоинт предназначен именно для такого вывода. На практике формулировка промпта это подкрепляет: называйте инструменты, описывайте настроение и указывайте отсутствие vocals. Промпты, требующие вокальной линии, противоречат назначению эндпоинта.

Где появляется аудио

Когда задача достигает успешного состояния, ответ со статусом содержит результат. Ожидайте, что аудио поставляется в виде отдельного URL для получения, а не в base64 в JSON статуса. Прочитайте ответ и извлеките URL для скачивания из задокументированного поля вывода.

result = wait_for_job(job_id, status_url, headers)
# 前几次仔细检查结果，然后固定该字段。
audio_url = result["output"]["audio_url"]   # 在 API 参考中确认字段名

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

Привычки при скачивании

Потоковая запись на диск. Музыкальные файлы большие; загрузка целиком в память — лишняя нагрузка, которой можно избежать.
Проверяйте тип содержимого. Сохраняйте файл с расширением, которое подсказывает ответ, а не с жёстко заданным.
Считайте URL временным. Скачивайте своевременно или сохраняйте URL, только если документация утверждает его стабильность. Копируйте байты в своё хранилище для долговременного сохранения.
Скачивайте один раз. Скачивание в цикле повторов без маркера завершения легко создаёт частичные файлы. Пишите во временное имя, переименовывайте после успеха.
Фиксируйте происхождение. Храните ID задачи и промпт вместе с файлом. Когда позже понадобится вариант, у вас будут точные входные данные.

Частые точки отказа и исправления

Большинство проблем первой интеграции попадает в короткий список. Вот контрольный перечень.

401 / 403 — аутентификация. Заголовок неверен, ключ отсутствует или переменная окружения разрешается в пустую строку. Убедитесь, что ключ задан в той же оболочке или процессе, где запускается код, и заголовок читается точно как Authorization: Bearer <key>.

400 — некорректная нагрузка. Отсутствует model, опечатка в mureka-9.5/instrumental, невалидный JSON или поле, которое эндпоинт не принимает. Отправьте сначала тело через curl, чтобы изолировать нагрузку от кода. Проверьте JSON перед отправкой; висячие запятые — классическая проблема.

415 или ошибка пустого тела — тип содержимого. Должен присутствовать Content-Type: application/json. Некоторые HTTP-клиенты устанавливают его автоматически при передаче json=, но не все.

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

Отсутствует URL для скачивания. Вы прочитали не то поле или прочитали ответ до того, как задача достигла терминального успешного состояния. Залогируйте один полный успешный ответ, подтвердите путь к URL аудио, затем зафиксируйте его.

Дублирующиеся генерации. Ваш опросчик упал, и что-то отправило задачу заново. Сохраняйте ID задачи до опроса и проверяйте существующие задачи перед отправкой новой.

Ограничения частоты. Отступайте с дрожанием при ответах 429 и ставьте работу в очередь, а не запускайте её одновременно из множества потоков.

Обрабатывайте их в этом порядке — аутентификация, нагрузка, тип содержимого, опрос, вывод — и обычно причина находится с первого раза. Как только вызов curl и его Python-двойник успешно пройдут от начала до конца, эндпоинт делает именно то, что требуется: превращает промпт в инструментальный трек и передаёт вам URL для скачивания.