Руководство

API minimax-music-3: руководство по curl и Python

Aug 18, 2026

Чтобы сгенерировать трек с помощью minimax-music-3 на hiapi, достаточно одного вызова POST /v1/tasks и последующего опроса — это в точности та же асинхронная схема задач, которую используют все модели на платформе. В этом руководстве приведены реальные запросы и ответы (создание задачи, опрос и итоговый URL аудио), поэтому код ниже можно скопировать и запустить, а не просто использовать как иллюстрацию.

Что вам понадобится

Ключ API hiapi — создайте его в консоли. Он отправляется в каждом запросе как Bearer-токен.
И это всё. В отличие от моделей генерации видео по изображению или изображений по изображению, minimax-music-3 не принимает никаких файлов или URL на вход — он генерирует только по тексту.

Минимальный рабочий запрос (curl)

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

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

Ответ:

{"code":200,"data":{"taskId":"tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55"},"message":"success"}

Опрашивайте задачу до её завершения:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

Пока задача выполняется, status последовательно проходит через handling → archiving и в итоге становится success (или failed). В тестах генерация одного трека от отправки до success заняла около двух с половиной минут. Ответ после завершения выглядит так:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url — это и есть WAV-файл. Обратите внимание на expireAt — прежде чем строить какие-либо функции, рассчитанные на долгосрочную доступность этого URL, прочитайте раздел о хранении ниже.

Тот же процесс на Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

Какие параметры minimax-music-3 действительно проверяет

Схема входа строгая — если отправить поля, которых нет в списке, API отклонит весь запрос ещё до того, как он попадёт в очередь:

prompt (строка, обязательный) — стиль, настроение, инструментовка. Именно это фактически определяет форму трека.
lyrics (строка, обязательный) — всегда обязателен, даже для чисто инструментальных треков. Передайте "[Instrumental]" в качестве заполнителя; для треков с вокалом используйте теги секций вроде [Verse] / [Chorus].
callback (объект, необязательный) — {"url": "...", "when": "final"}. Единственное поддерживаемое значение when — "final"; любое другое значение вернёт 400 с сообщением invalid callback.when: only 'final' is supported.

Если отправить что-либо за пределами этих трёх ключей верхнего уровня — например, sample_rate, duration или опечатку — вы получите:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

Замечания для продакшена

Две разные формы ошибок. Ошибки валидации (отсутствующее поле, неверное значение перечисления, неизвестный ключ) возвращаются на верхнем уровне как {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Ошибки аутентификации/прав доступа возвращаются как {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — вложенный объект error, HTTP 401. Проверяйте обе формы в обработке ошибок; код, проверяющий только resp["code"], пропустит случай 401.
permission_denied означает проблему с ключом, а не с запросом. Если prompt/lyrics присутствуют и имеют правильные типы, но вы всё равно получаете 401 permission_denied, значит у самого ключа API не включена эта модель — проверьте его в консоли, а не перечитывайте свой JSON.
Хранилище выходных файлов временное. storage: "temp" и метка времени Unix expireAt у каждого вывода — в зафиксированном примере это примерно 7 дней после создания. Как только задача успешно завершилась, сразу скачайте файл или перенесите его в собственное хранилище; не сохраняйте URL temp.hiapi.ai как постоянную ссылку.
Для любых пакетных задач используйте callback. Опрашивать один трек нормально; опрашивать пятьдесят — это пятьдесят повторяющихся запросов. Задайте callback.url и when: "final", чтобы hiapi один раз отправил вам результат, когда задача действительно завершится.
Повторяйте попытку до получения taskId, а не после. Повтор при сетевой ошибке или 5xx на начальном POST /v1/tasks безопасен — на тот момент ещё ничего не создано. Как только у вас появился taskId, повторная отправка того же prompt создаст ещё один, не связанный с ним трек; в этот момент следует опрашивать задачу или ждать callback.

Связанные материалы

Страница модели minimax-music-3 — актуальная цена и онлайн-демо.
Тарифы hiapi — расценки на все модели каталога.
Документация hiapi — полный справочник API, выходящий за рамки этой одной модели.

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

Нужно ли указывать текст песни для чисто инструментальных треков? Да — lyrics является обязательным полем независимо от того, нужен ли вам вокал. Передайте "[Instrumental]", и модель сгенерирует трек без вокала.

Можно ли полностью избежать опроса? Да, задайте при создании задачи callback: {"url": "https://your-endpoint", "when": "final"}. Когда задача достигнет конечного состояния, hiapi отправит POST на ваш URL с той же нагрузкой, что и GET /v1/tasks/:id. В настоящее время "final" — единственное поддерживаемое значение when.

Почему я получаю "additional properties not allowed"? Схема входа minimax-music-3 принимает внутри input только prompt и lyrics (плюс callback на верхнем уровне). Любое другое имя поля — даже если оно работает в других моделях hiapi — будет отклонено до запуска запроса.

Почему ключ, работающий с другими моделями, возвращает 401 на этой модели? Доступ к моделям предоставляется на уровне ключа. Ответ 401 с error_code: "permission_denied" означает, что этому конкретному ключу ещё не предоставлены права на minimax-music-3 — включите их в консоли; это не ошибка в вашем теле запроса.

Сколько я могу ждать перед скачиванием выходного файла? Не ждите — output[0].url является временной ссылкой (на практике expireAt примерно через неделю). Рассматривайте её как одноразовую передачу: скачайте или загрузите заново сразу после успешного завершения задачи.