minimax-music-3 API：curl と Python ガイド

hiapi で minimax-music-3 を使って楽曲を 1 曲生成するには、1 回の POST /v1/tasks 呼び出しとポーリングだけで済みます。これはプラットフォーム上のすべてのモデルが使用する非同期タスクパターンと完全に同じです。本ガイドでは実際のリクエストとレスポンス（タスク作成、ポーリング、最終的な音声 URL）を記録しているため、以下のコードは単なる例示ではなく、そのままコピーして実行できます。

必要なもの

1. hiapi API キー——コンソールで作成します。毎回のリクエストで Bearer トークンとして送信されます。
2. 以上です。画像から動画、画像から画像を生成するモデルとは異なり、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）になります。テストでは、1 曲が送信から success になるまで約 2 分半かかりました。完了後のレスポンスは次のとおりです：

{
  "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" です。それ以外の値を指定すると、invalid callback.when: only 'final' is supported というエラーで 400 が返ります。

これら 3 つのトップレベルキー以外の何か——sample_rate、duration、あるいは誤字など——を送信すると、次のレスポンスが返ります：

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

本番環境での注意点

• 2 種類の異なるエラー形式。 検証エラー（フィールド不足、列挙値の誤り、未知のキー）はトップレベルで {"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" と、各出力の expireAt Unix タイムスタンプ——キャプチャした例では、作成から約 7 日後です。タスクが成功したらすぐにファイルをダウンロードするか、独自のストレージにプッシュしてください。temp.hiapi.ai の URL を永続リンクとして保存しないでください。
• バッチ処理ではコールバックを使用してください。 1 曲のポーリングなら問題ありませんが、50 曲のポーリングは 50 回の往復になります。callback.url と when: "final" を設定すると、hiapi がタスクの真の完了時に結果を一度だけプッシュします。
• 再試行は taskId を取得する前に行ってください。 最初の POST /v1/tasks でネットワークエラーや 5xx が発生した場合の再試行は安全です——この時点ではまだ何も作成されていません。一度 taskId を取得した後に同じ prompt を再送信すると、別の無関係な曲が作成されます。その場合はポーリングするかコールバックを待ってください。

関連コンテンツ

• minimax-music-3 モデルページ——現在の価格とオンライン体験エリア。
• hiapi の料金——カタログ内のすべてのモデルの料金。
• hiapi ドキュメント——この単一モデルを超えた完全な API リファレンス。

よくある質問

純粋なインストゥルメンタル曲でも歌詞を提供する必要がありますか？ はい——ボーカルが欲しいかどうかに関係なく、lyrics は必須フィールドです。"[Instrumental]" を渡すと、モデルは歌唱なしの曲を生成します。

ポーリングを完全に避けることはできますか？ はい、タスク作成時に callback: {"url": "https://your-endpoint", "when": "final"} を設定します。タスクが終了状態に達すると、hiapi は GET /v1/tasks/:id と同じペイロードをあなたの URL に POST します。"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 は約 1 週間後です）。これを一度限りの受け渡しと考え、タスク成功後すぐにダウンロードするか再アップロードしてください。