MiniMax Music API（minimax-music-1.5）の使い方：curl、Python、実行可能なリクエスト

このガイドでは、hiapi の統一タスク API 上で minimax-music-1.5 を使用し、スタイルプロンプトと歌詞から、ボーカル、楽器、曲構成を含む1曲の完全な楽曲を生成する方法を説明します。以下の内容はすべて実際のエンドポイントで検証済みで、そのままコピー＆ペーストして実行できます。

何を構築するか、そして何を用意するか

目標：音楽スタイルのテキスト記述と歌詞を送信し、ダウンロード可能なオーディオトラックを取得すること。

必要なものは1つだけです：hiapi API キー。ダッシュボードから取得してください——sk- で始まります。以下のすべての例では、これが環境変数に保存されていることを前提としています：

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

hiapi 上の音楽生成は、他のすべてのモデルと同じ非同期タスクインターフェースを使用します：POST /v1/tasks でタスクを作成し、その後 GET /v1/tasks/<taskId> をポーリングするか、タスク完了時にコールバックを受信します。

入力スキーマ（検証済み）

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 のいずれか。

つまずきやすいポイントが2つあります：

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 秒ごとにポーリングし、完了したトラックをローカルに保存します。

本番環境パターン

ポーリングの代わりにコールバックを使用する

簡単なスクリプトの範囲を超える用途では、コールバックを登録し、タスクが終了状態に達したときに hiapi から結果をプッシュしてもらいましょう。トップレベルの callback オブジェクトを追加します（model と同じ階層で、input の内部ではありません）：

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

"when": "final" のみサポートされています——タスクの成功または失敗時に 1 回の POST を受信し、増分の進捗イベントは受信しません。ポーリングは開発や一度きりのタスクに適しています。大量のトラックを生成する場合やキュー待ちで実行する場合は、開いたループを維持する必要がなく、高頻度のポーリングによるレート制限も回避できるため、コールバックの方が優れています。コールバックがまったく届かない場合は、hiapi タスクのコールバックが発火しない理由のチェックリストに沿って確認してください。

冪等性とリトライ

タスク作成自体は冪等ではありません：タイムアウトした POST /v1/tasks をリトライすると、2 つのタスクが作成される可能性があります（そして 2 回課金されます）。作成呼び出しが返った直後に taskId を永続化し、再起動時は盲目的に再送信するのではなく、その id をポーリングして復元してください。タスクが止まっているように見えても、すぐに kill して再作成しないでください——hiapi /v1/tasks タスクのハングまたはタイムアウト時を参照して、遅いタスクと死んだタスクを区別する方法を確認してください。

エラーハンドリング

2 種類の失敗は異なる現れ方をします：

• リクエストレベルのエラーは同期的に返されます。無効または未認証のキーは permission_denied エラー（"This API key cannot use the selected model..."）を返し、サポートチームに提示できる request_id が付属します。スキーマ違反は 400 INVALID_REQUEST を返し、prompt: minLength: got 1, want 10 のような正確な情報が付きます。
• タスクレベルの失敗はポーリング/コールバック結果に現れ、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 はどの入力フィールドを受け付けますか？

ちょうど4つです：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 は期限切れになります。

ポーリングとコールバックのどちらを使うべきですか？

開発や単一のタスクではポーリングを使用してください（5 秒間隔で十分です）。本番環境では when: "final" 付きの callback を使用し、接続を開いたままにしないようにしてください——特にトラックを一括生成する場合に重要です。

なぜ permission_denied が返されるのですか？

キーが無効か、そのモデルへのアクセス権限がありません。ダッシュボードでキーを確認し、Authorization: Bearer sk-... の形式で送信していることを確認してください。