Как использовать MiniMax Music API (minimax-music-1.5): curl, Python и рабочие запросы

В этом руководстве объясняется, как использовать minimax-music-1.5 в едином task API hiapi для генерации полноценной песни — с вокалом, инструментами и структурой — по стилевому промпту и тексту песни. Всё ниже проверено на реальном эндпоинте: можно копировать, вставлять и запускать.

Что вы создаёте и что нужно подготовить

Цель: отправить текстовое описание музыкального стиля и текст песни и получить загружаемую аудиодорожку.

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

export HIAPI_KEY="sk-your-key-here"

Генерация музыки в hiapi использует тот же интерфейс асинхронных задач, что и все остальные модели: POST /v1/tasks создаёт задачу, затем вы либо опрашиваете GET /v1/tasks/<taskId>, либо получаете callback по завершении задачи.

Схема входных данных (проверено)

minimax-music-1.5 принимает в input следующие поля — любые другие будут отклонены с кодом 400:

Поле	Обязательно	Тип	Ограничения
prompt	Да	string	10–300 символов. Описывает жанр, настроение, инструментовку и стиль вокала.
lyrics	Да	string	10–600 символов. Текст песни для вокала; поддерживаются структурные теги вроде [Verse] и [Chorus].
sample_rate	Нет	integer	Одно из: 16000, 24000, 32000, 44100.
bitrate	Нет	integer	Одно из: 32000, 64000, 128000, 256000.

Два распространённых подводных камня:

1. prompt и lyrics оба обязательны. prompt управляет тем, как звучит; lyrics управляет тем, о чём поют. Без любого из них вы получите invalid input: ... missing required field.
2. Схема строгая. Поля, которые вы могли ожидать по аналогии с другими музыкальными API — duration, seed, format, instrumental — не принимаются. Их отправка вернёт additional properties ... not allowed.

Минимальный рабочий пример: curl

Создание задачи:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "Uplifting acoustic pop, warm female vocals, gentle guitar and light percussion",
      "lyrics": "[Verse]\nMorning light on a quiet street\nCoffee steam and a steady beat\n[Chorus]\nWe keep on going, we find our way\nOne small step at a time, every day",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

При успешном создании возвращается id задачи:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Затем опрашивайте, пока задача не достигнет терминального состояния:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

Пока задача выполняется, вы увидите нетерминальный status; по завершении status становится success, а URL аудио появляется в output:

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

Скачайте файл как можно скорее — URL вывода имеет ограниченный срок действия, и его следует рассматривать как окно для получения, а не как постоянное хранилище:

curl -o track.mp3 "https://.../track.mp3"

Полный скрипт на Python: отправка, опрос, скачивание

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("Uplifting acoustic pop, warm female vocals, "
                       "gentle guitar and light percussion"),
            "lyrics": ("[Verse]\nMorning light on a quiet street\n"
                       "Coffee steam and a steady beat\n"
                       "[Chorus]\nWe keep on going, we find our way\n"
                       "One small step at a time, every day"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

Запустите его командой python3 make_song.py. Скрипт отправит задачу, будет опрашивать её каждые 5 секунд и сохранит готовую дорожку локально.

Режимы для продакшена

Callback вместо опроса

Для любого использования, выходящего за рамки быстрого скрипта, зарегистрируйте callback, чтобы hiapi отправлял вам результат по достижении задачей терминального состояния. Добавьте объект верхнего уровня callback (он на одном уровне с model, а не внутри input):

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

Поддерживается только "when": "final" — вы получите один POST при успехе или неудаче задачи, а не инкрементальные события прогресса. Опрос подходит для разработки и разовых задач; callback предпочтительнее, когда вы генерируете много дорожек или работаете в условиях очереди, поскольку вам не нужно держать открытый цикл и вы не рискуете упереться в лимиты частоты из-за частого опроса. Если callback так и не приходит, пройдитесь по чек-листу в статье почему ваш callback задачи hiapi не срабатывает.

Идемпотентность и повторы

Создание задачи само по себе не идемпотентно: повторная попытка после таймаута POST /v1/tasks может создать две задачи (и списать плату дважды). Сохраните taskId сразу после того, как вызов создания вернулся, и при перезапуске восстанавливайтесь, опрашивая этот id, а не отправляя задачу заново вслепую. Если задача выглядит зависшей, не убивайте её и не создавайте новую сразу — см. когда задача hiapi /v1/tasks зависает или истекает по таймауту, чтобы понять, как отличить медленную задачу от мёртвой.

Обработка ошибок

Два типа сбоев проявляются по-разному:

• Ошибки уровня запроса возвращаются синхронно. Неверный или неавторизованный ключ возвращает ошибку permission_denied ("This API key cannot use the selected model...") вместе с request_id, который можно указать при обращении в поддержку. Нарушения схемы возвращают 400 INVALID_REQUEST с точным сообщением, например prompt: minLength: got 1, want 10.
• Сбои уровня задачи появляются в результате опроса/callback как status: "fail" с error.code и error.message — вызов создания прошёл успешно, но генерация не удалась. Именно эти сбои должны попадать в логику повторных попыток.

Проверяйте длину на клиенте до отправки: prompt — не более 300 символов, lyrics — не более 600 символов; API отклонит слишком длинный ввод, а не обрежет его.

Цены и ограничения

MiniMax Music 1.5 тарифицируется за сгенерированную дорожку по модели оплаты за использование — актуальные тарифы смотрите на странице цен hiapi и на странице модели minimax-music-1.5, где также можно попробовать модель в playground ещё до написания кода.

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

Какие входные поля принимает minimax-music-1.5?

Ровно четыре: prompt (обязательно, 10–300 символов), lyrics (обязательно, 10–600 символов), sample_rate (необязательно, 16000/24000/32000/44100) и bitrate (необязательно, 32000/64000/128000/256000). Любые другие поля будут отклонены с ошибкой additional properties not allowed.

Можно ли управлять структурой песни?

Да — используйте в lyrics структурные теги вроде [Verse] и [Chorus] для организации. Модель использует эти теги для формирования аранжировки. Вся строка текста песни (включая теги) должна укладываться в лимит 600 символов.

Можно ли генерировать чисто инструментальную музыку?

В схеме входных данных нет переключателя инструментала. Этот эндпоинт управляется текстом песни, поэтому описывайте желаемую инструментовку и настроение в prompt; для чисто инструментальных сценариев смотрите актуальный список возможностей на странице модели.

Как получить аудиофайл?

Когда статус задачи success, ссылка на скачивание хранится в data.output[0].url. Загрузите её сразу и сохраните байты у себя — URL вывода истекает.

Что использовать: опрос или callback?

Для разработки и отдельных задач используйте опрос (интервала в 5 секунд достаточно). В продакшене используйте callback с when: "final", чтобы не держать соединение открытым — особенно при пакетной генерации дорожек.

Почему я получаю permission_denied?

Ваш ключ недействителен или у него нет доступа к этой модели. Проверьте ключ в дашборде и убедитесь, что отправляете его в виде Authorization: Bearer sk-....