HiAPI
Блог

Руководство

Руководство по API minimax-music-1.5: curl и Python Requests

Nov 12, 2026
Обложка: на тёплом угольном фоне широкая янтарная полоса света наискось пересекает узкую щель, дополненная сдержанными тёмными геометрическими блоками; композиция сдержанная, с обилием свободного пространства.
На этой странице

Требования minimax-music-1.5 к запросу

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

На высоком уровне запрос к minimax-music-1.5 включает:

  • Описание стиля или промпт — музыкальное направление: жанр, настроение, инструментовка, ощущение темпа, особенности продакшена.
  • Текст песни — при наличии вокала, слова, которые действительно поются. Для чисто инструментальных запросов оставьте пустым или опустите.
  • Управление структурой — например, целевая длительность генерируемого трека, ограничивающая длину композиции модели.
  • Идентификатор модели — minimax-music-1.5 — направляет задачу через шлюз к правильному бэкенду.

Ментальная модель, которую стоит запомнить: стилевой вход говорит модели, как это должно звучать, а текстовый вход говорит, о чём поётся. Они не взаимозаменяемы. Если вы вставите описание жанра в поле текста, получите хаотичный результат; если оставите текст пустым, но запросите трек с вокалом, модель просто придумает его сама. Прежде чем начать, определите, в каком из двух режимов вы находитесь.

Перед написанием кода нужно усвоить ещё два момента:

  1. Генерация музыки не мгновенна. Создание готового трека требует реального времени вычислений, поэтому API по своей природе асинхронен. Вы отправляете задачу, затем получаете результат. Любое руководство, показывающее только один блокирующий вызов, скрывает от вас цикл опроса.
  2. Вывод доставляется по ссылке. Вы получаете URL сгенерированного аудио, а не встроенные сырые байты. Их нужно скачать или передать потоком отдельно.

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

Начальная настройка на HiAPI

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

API-ключ

Создайте ключ в консоли вашей учётной записи HiAPI. Относитесь к нему как к паролю: он аутентифицирует каждый запрос и привязан к использованию вашей учётной записи. Никогда не коммитьте его в репозиторий, не вставляйте в публичные gist и не включайте в мобильные или браузерные бандлы.

Базовый адрес интерфейса

Все вызовы отправляются на шлюз HiAPI, который предоставляет minimax-music-1.5 за единым унифицированным интерфейсом. Вам не нужны отдельные учётные данные или SDK для каждой модели — имя модели в теле запроса выбирает бэкенд. Обратитесь к справочной документации API, чтобы получить точный базовый URL и текущий путь запроса.

Держите ключ вне исходного кода

Подход, работающий от временного скрипта до продакшена, — переменные окружения:

export HIAPI_API_KEY="your-key-here"

Затем читайте её во время выполнения. В Python это os.environ["HIAPI_API_KEY"]; в shell — $HIAPI_API_KEY. Если вы локально используете файл .env, добавьте его в .gitignore до первого коммита — а не после. Для развёрнутого сервиса внедряйте ключ через менеджер секретов платформы, а не запекайте его в образ.

Сделайте быструю проверку перед тем, как что-то строить: убедитесь, что процесс, который вы собираетесь запустить, видит этот ключ (выполните echo $HIAPI_API_KEY в том же shell). Большинство сообщений о «сбое аутентификации» объясняются тем, что ключ экспортирован в одном терминале, а скрипт запущен в другом.

Первый рабочий запрос через curl

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

curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "prompt": "тёплый инди-фолк, фингерстайл на акустической гитаре, мягкие щёточные барабаны, интимный близкий вокал",
    "lyrics": "[verse]\nУтренний свет ложится на кухонный пол\n[chorus]\nМы всё ещё здесь, мы всё ещё здесь",
    "duration": 30
  }'

Построчно:

  • -X POST — генерация — это операция создания, а не чтения.
  • Authorization: Bearer $HIAPI_API_KEY — ключ из предыдущего раздела, раскрываемый shell, поэтому, пока вы ссылаетесь на переменную, он не попадёт в вашу историю.
  • Content-Type: application/json — шлюз ожидает JSON; пропуск этого заголовка — частая причина запутанных 4xx-ответов.
  • model — привязывает запрос к minimax-music-1.5.
  • prompt — описание стиля. Указывайте инструментовку и настроение конкретно, а не одним прилагательным.
  • lyrics — текст для пения, с лёгкими структурными тегами вроде [verse] и [chorus] в качестве подсказок структуры. Экранирование \n — это символ новой строки в JSON.
  • duration — ограничивает длину сгенерированного трека в секундах.

Возвращается ссылка на задачу, а не аудио. Захватите её:

curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | tee job.json

Чтение тела запроса из файла с помощью -d @payload.json сохраняет историю shell чистой и делает переход к Python простым — этот файл и есть тело запроса. Изучите ответ, запишите идентификатор задачи или task и любые поля статуса; этот идентификатор понадобится для получения результата.

Перенос запроса в Python

Версия на Python должна ощущаться как перенос вызова curl, а не переписывание. Используйте requests, читайте ключ из переменных окружения и держите тело запроса в виде словаря для читаемости.

import os
import json
import requests

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

payload = {
    "model": "minimax-music-1.5",
    "prompt": "тёплый инди-фолк, фингерстайл на акустической гитаре, мягкие щёточные барабаны, интимный близкий вокал",
    "lyrics": "[verse]\nУтренний свет ложится на кухонный пол\n[chorus]\nМы всё ещё здесь, мы всё ещё здесь",
    "duration": 30,
}

response = requests.post(
    f"{BASE_URL}/minimax-music-1.5",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))

Несколько замечаний по переносу, чтобы избежать сюрпризов:

  • Используйте json.dumps с data= или json=payload. Оба варианта работают; json=payload заставит requests установить тип содержимого за вас. Если передать словарь напрямую в data= без сериализации, сервер получит тело в формате формы и отклонит его.
  • Всегда задавайте timeout. Без него зависшее соединение будет бесконечно подвешивать процесс. Помните, что этот таймаут покрывает отправку, а не генерацию — этим занимается следующий раздел.
  • Вызывайте raise_for_status() перед разбором. Он превращает 4xx или 5xx в понятное исключение, а не загадочный KeyError при обращении к несуществующему полю.
  • Сохраняйте объект ответа. При отладке печать response.status_code и response.text даёт гораздо больше информации, чем разобранная ошибка.

Результат этого скрипта — та же ссылка на задачу, что и у curl. Всё после отправки — опрос, повторные попытки, загрузка — совершенно одинаково в обоих языках, и именно поэтому это заслуживает отдельного раздела.

Обработка жизненного цикла асинхронной задачи

Самая распространённая ошибка при генерации музыки — считать её чат-дополнением: отправить, подождать, прочитать трек. Вызов отправки возвращается быстро, но аудио ещё не существует. Ваш код должен замкнуть цикл.

Три состояния

Каждая задача проходит через небольшой конечный автомат:

  1. Отправлено (Submitted) — вы получили идентификатор задачи, работа в очереди или выполняется.
  2. Завершено (Finished) — аудио готово, ответ содержит URL к нему.
  3. Ошибка (Failed) — генерация прервана; ответ объяснит причину.

Ваш цикл опроса должен различать все три состояния. Статус submitted означает «продолжайте ждать», а не «повторите попытку».

Опрашивайте, а не бомбардируйте

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

import time

def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "finished":
            return data
        if status == "failed":
            raise RuntimeError(f"job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} not finished after {max_wait}s")

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

Повторяйте правильный объект

Повторные попытки относятся к двум разным уровням, и их смешение приводит к дублированию работы. Повтор на уровне транспорта — сам HTTP-вызов не удался из-за 5xx или сброса соединения — безопасен для запросов опроса. Повтор генерации — это новая отправка, которая снова стоит одного рендеринга, поэтому делайте его только когда задача явно сообщает об ошибке и ограничивайте количество попыток. Никогда не повторяйте отправку из-за медленного опроса.

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

Настройка входных данных текста, стиля и длительности

Получить пригодный трек от minimax-music-1.5 — в основном вопрос осознанного написания этих двух текстовых полей. Несколько привычек определяют, будет ли результат обобщённым или тем, что вы действительно готовы выпустить.

Пишите стилевой промпт как бриф продюсера

Одно слово жанра даёт модели слишком много свободы. Сложите конкретные измерения:

  • Жанр и эпоха — «трип-хоп конца 90-х» лучше, чем «электроника».
  • Инструментовка — назовите ведущие инструменты и ритм-секцию.
  • Настроение и энергия — «меланхолично, но с драйвом» создаёт напряжение, которое не выразить одним прилагательным.
  • Особенности продакшена — «lo-fi, ленточное насыщение, широкий стереообраз» направляет сведение.

Уложитесь в одно-два предложения. Длинные абзацы промптов обычно размывают, а не уточняют.

Структурируйте текст песни тегами

Лёгкие маркеры разделов — [verse], [chorus], [bridge] — дают модели карту маршрута и обычно приводят к более чёткой структуре песни, чем неразмеченный блок текста. Держите каждую строку достаточно короткой для пения; строка из двенадцати слов редко ложится на мелодию. Для инструментальных треков полностью опускайте lyrics, а не отправляйте пустую строку с текстом о стиле внутри.

Согласуйте длительность с материалом

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

Итерируйте небольшими изменениями

Когда трек близок, но не тот, меняйте один вход за раз — инструментовку в промпте, или слово темпа, или ту строчку текста. Изменение всего сразу не позволит понять, какое поле дало улучшение. Сохраняйте лучшее тело запроса в файл и ветвитесь от него.

Устранение распространённых ошибок

Большинство сбоев попадают в несколько узнаваемых категорий. Сопоставьте симптом, примените исправление и двигайтесь дальше.

Сбои аутентификации

Симптом: 401 или 403 с сообщением об учётных данных.

  • Убедитесь, что заголовок — Authorization: Bearer <key>; слово Bearer и пробел обязательны.
  • Проверьте, что переменная окружения действительно установлена в процессе, отправляющем запрос. Ключ, экспортированный в одном shell, не достигнет cron-задания или Docker-контейнера.
  • Проверьте лишние пробелы или переводы строк, скопированные вместе с ключом.

Некорректное тело запроса

Симптом: 400 с сообщением валидации.

  • Отправляйте Content-Type: application/json. Отсутствие этого заголовка заставит сервер неправильно понять совершенно правильное тело запроса.
  • Если используете requests, передавайте json=payload или data=json.dumps(payload). Передача сырого словаря в data= кодирует его как форму.
  • Сверьте имена и типы полей со справочной документацией API: model должен быть ровно minimax-music-1.5, duration — целым числом, переводы строк в тексте должны быть корректно экранированы как \n в JSON.
  • Если сомневаетесь, используйте curl -d @payload.json, чтобы изолированно проверить валидность самого тела запроса до того, как задействовать Python.

Таймауты и ошибки соединения

Симптом: запрос зависает или выбрасывает ошибку соединения.

  • Задавайте явный timeout для каждого вызова. Таймаут отправки должен быть достаточно щедрым, чтобы покрыть задержку очереди, но это не время рендеринга.
  • Не делайте таймаут опроса равным общему max_wait; одна медленная проверка статуса не должна прерывать всё ещё выполняющуюся задачу.
  • Если отправка повторно истекает по таймауту, а опрос успешен, ваше тело запроса может быть слишком большим — сократите текст.

Ошибки опроса

Симптом: вы продолжаете опрашивать, но никогда не видите finished, или опрашиваете не тот ресурс.

  • Убедитесь, что используете идентификатор задачи из ответа на отправку, а не ID запроса или заголовок корреляции.
  • Считайте submitted/running означающим «продолжайте ждать», а не «повторите отправку». Повторная отправка создаст второй трек.
  • Добавьте задержку. Агрессивный опрос вызывает ограничение скорости, которое выглядит как сбой, но на самом деле создано вами.
  • Если задача сообщает failed, прочитайте сообщение перед повторной отправкой — недопустимые теги текста или длительность вне диапазона будут снова и снова терпеть неудачу одинаково.

Если застряли, вернитесь к исходному вызову curl с -v, чтобы увидеть фактическую строку статуса и заголовки. Этот шаг устраняет большинство неоднозначностей быстрее, чем любое количество отладки в Python.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API