チュートリアル
minimax-music-1.5 API チュートリアル:curl と Python Requests
このページの内容
minimax-music-1.5 がリクエストに求めるもの
最初のコードを書く前に、1 回の音楽生成呼び出しが何を含むのかを明確にしておくのがよいでしょう。テキスト補完とは異なり、音楽リクエストには役割の異なる 2 つのクリエイティブ入力に加え、出力を形成するためのいくつかの制御項目があります。
高レベルでは、minimax-music-1.5 のリクエストは次のものを含みます:
- スタイルまたはプロンプト記述 —— 音楽の方向性:ジャンル、ムード、楽器編成、テンポ感、プロダクションの特徴。
- 歌詞 —— 曲にボーカルが含まれる場合、実際に歌われるテキスト。インストゥルメンタルのリクエストでは空にするか省略します。
- 構造制御 —— 生成曲の目標長さなど。モデルが作曲する長さを制限します。
- モデル識別子 ——
minimax-music-1.5—— ゲートウェイがタスクを正しいバックエンドにルーティングできるようにします。
心に留めておくべきメンタルモデル:スタイル入力はモデルにどう聴こえるべきかを伝え、歌詞入力はモデルに何が歌われるかを伝えます。両者は入れ替え不可です。ジャンルの説明を歌詞フィールドに入れると混乱した出力になりますし、歌詞を空にしてボーカル付きの曲を要求すれば、モデルは勝手に作り上げるしかありません。始める前に、自分が 2 つのモードのどちらにいるのかを決めてください。
コードを書く前にさらに 2 点を腹落ちさせておきましょう:
- 音楽生成は即時ではありません。 完成した曲の生成には実際の計算時間がかかるため、この API は設計上非同期です。ジョブを送信し、後から結果を取得します。1 回のブロッキング呼び出しだけを示すチュートリアルは、ポーリングループをあなたから隠しています。
- 出力は参照として配信されます。 受け取るのは生成された音声の URL であり、インラインの生バイトではありません。別途ダウンロードまたはストリーミングする必要があります。
これら 3 つのこと——スタイルと歌詞の区別、非同期ライフサイクル、URL ベースの出力——を明確に説明できれば、実際のリクエストボディは容易に読めます。
HiAPI での初期設定
初回呼び出しの前に 3 つ必要です:API キー、ベースエンドポイント URL、そしてキーをハードコードしない習慣です。
API キー
HiAPI アカウントのコンソールでキーを作成します。パスワードのように扱ってください:すべてのリクエストを認証し、アカウントの使用量に紐づきます。バージョン管理にコミットしない、公開 gist に貼らない、モバイルやブラウザのバンドルにパッケージしないこと。
ベースエンドポイント URL
すべての呼び出しは HiAPI ゲートウェイに送信され、単一の統一インターフェースの背後で minimax-music-1.5 を公開します。モデルごとに個別の認証情報や SDK を用意する必要はありません——リクエストボディのモデル名がバックエンドを選択します。正確なベース URL と現在のリクエストパスについては API リファレンスを参照してください。
キーをソースコードから遠ざける
使い捨てスクリプトから本番環境まで通用するパターンは環境変数です:
export HIAPI_API_KEY="your-key-here"
そして実行時に読み取ります。Python では os.environ["HIAPI_API_KEY"]、シェルでは $HIAPI_API_KEY です。ローカルで .env ファイルを使う場合は、最初のコミットの前に .gitignore へ追加してください——後からではなく。デプロイしたサービスでは、イメージに埋め込むのではなく、プラットフォームのシークレットマネージャー経由でキーを注入します。
何かを構築する前にちょっとした確認を:これから実行するプロセスがキーを見えるか確かめてください(同じシェルで echo $HIAPI_API_KEY)。「認証失敗」の報告の多くは、あるターミナルでキーをエクスポートし、別のターミナルでスクリプトを実行したことに起因します。
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—— 前節のキーをシェルが展開するため、変数を参照する限り履歴に残りません。Content-Type: application/json—— ゲートウェイは JSON を期待します。このヘッダーを省略すると不可解な 4xx 応答のよくある原因になります。model—— リクエストを minimax-music-1.5 に固定します。prompt—— スタイル記述。単なる形容詞 1 つではなく、楽器編成とムードを具体的に述べます。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 でリクエストボディをファイルから読み取れば、シェル履歴をきれいに保て、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))
予期せぬ事態を避けるための移植上の注意点:
data=とともにjson.dumpsを使うか、json=payloadを使います。 どちらでも動作しますが、json=payloadならrequestsがコンテンツタイプを設定してくれます。辞書をシリアライズせずにそのままdata=に渡すと、サーバーはフォームエンコードされたボディを受け取り拒否します。- 必ず
timeoutを設定します。 設定しないと、停滞した接続でプロセスが無期限にハングします。このタイムアウトが対象とするのは送信であり、生成ではないことを覚えておいてください——それは次の節で扱います。 - パースの前に
raise_for_status()を呼びます。 これにより 4xx や 5xx が、存在しないフィールドにアクセスしたときの不可解なKeyErrorではなく、明確な例外になります。 - レスポンスオブジェクトを保持します。 デバッグ時には
response.status_codeとresponse.textを出力する方が、パース済みのエラーよりはるかに多くの情報を教えてくれます。
このスクリプトの結果は curl が生成するジョブ参照と同じです。送信後のすべて——ポーリング、リトライ、ダウンロード——はどちらの言語でも完全に同一であり、だからこそ別の節を設ける価値があるのです。
非同期タスクのライフサイクルを扱う
音楽生成で最もよくある間違いは、チャット補完のように扱うことです:送信し、待ち、曲を読む。送信呼び出しはすぐに返りますが、音声はまだ存在しません。コードはループを閉じる必要があります。
3 つの状態
すべてのジョブは小さなステートマシンを通過します:
- 送信済み(Submitted) —— ジョブ識別子を取得し、処理はキュー待ちまたは実行中です。
- 完了(Finished) —— 音声の準備ができ、応答にその URL が含まれます。
- 失敗(Failed) —— 生成が中止され、応答が理由を説明します。
ポーリングループは 3 つの状態すべてを区別できるべきです。状態が 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 リファレンスを参照してください——上記の名前は例示とみなし、ドキュメントの値に合わせてください。
正しい対象をリトライする
リトライには 2 つの異なる層があり、混同すると作業の重複を招きます。トランスポートリトライ——HTTP 呼び出し自体が 5xx や接続リセットで失敗する——はポーリングリクエストに対して安全に繰り返せます。生成リトライは新たな送信であり、レンダリングをもう一度消費するため、ジョブが明確に失敗を報告した場合にのみ、回数を制限して行います。ポーリングが遅いという理由で送信をリトライしないでください。
最後に、ジョブ識別子を受け取った瞬間に永続化してください。送信と完了の間でプロセスがクラッシュした場合、その識別子は完了した曲を再生成のコストなしで復元する唯一の手段です。
歌詞・スタイル・長さの入力を調整する
minimax-music-1.5 から使える曲を得るには、主に 2 つのテキストフィールドを意識的に書くことが重要です。いくつかの習慣が、出力が凡庸なものになるか、本当にリリースしたいものになるかを決めます。
スタイルプロンプトをプロデューサーのブリーフのように書く
単一のジャンル語ではモデルに自由を与えすぎます。具体的な次元を積み重ねます:
- ジャンルと年代 —— 「90 年代後半のトリップホップ」は「エレクトロニック」より優れています。
- 楽器編成 —— リード楽器とリズム隊を名指しします。
- ムードとエネルギー —— 「メランコリックだが推進力がある」は単一の形容詞では表せない緊張感を生みます。
- プロダクションの特徴 —— 「lo-fi、テープサチュレーション、ワイドステレオ」がミックスを導きます。
1〜2 文に収めてください。長い段落のようなプロンプトは洗練させるのではなく薄める傾向があります。
タグで歌詞の構造を組織する
軽量なセクション標識——[verse]、[chorus]、[bridge]——はモデルにロードマップを与え、通常はタグのない一塊のテキストより明確な曲構造を生みます。各行は歌えるほど短く保ってください。12 語の行がメロディに収まることはまれです。インストゥルメンタルの曲では、スタイルテキストを入れた空文字列を送るのではなく、lyrics を完全に省略します。
長さを素材に合わせる
長さは作曲を制限します。完全な verse-chorus-verse の歌詞表に短い長さを組み合わせると圧縮を強いられ、慌ただしく聴こえます。2 行の歌詞に長い長さを組み合わせると繰り返しを招きます。まず曲の形を決め、それに合う長さを設定してください。より長い作品が必要なら、時間を引き延ばしてうまくいくことを期待するのではなく、歌詞を拡張しましょう。
小さな変更で反復する
曲が近いが違うときは、一度に1 つの入力だけを変えます——プロンプトの楽器編成、テンポの語、うまくいかなかった歌詞の一行など。すべてを同時に変えると、どのフィールドが改善をもたらしたのか分からなくなります。最良のリクエストボディをファイルに保存し、そこから分岐させてください。
よくあるエラーのトラブルシューティング
ほとんどの失敗は少数の识别可能なカテゴリに収まります。症状を照合し、修正を適用し、先に進みましょう。
認証失敗
症状: 401 または 403、認証情報に関するメッセージ。
- ヘッダーが
Authorization: Bearer <key>であることを確認します——Bearerという語とスペースが必要です。 - 環境変数がリクエストを発行するプロセスに実際に設定されているか検証します。あるシェルでエクスポートしたキーは cron ジョブや Docker コンテナには届きません。
- キーと一緒にコピーされた余分な空白や改行を確認します。
不正な形式のリクエストボディ
症状: 400、検証メッセージ付き。
Content-Type: application/jsonを送信します。このヘッダーがないと、サーバーは完全に正しいリクエストボディを誤解します。requestsを使う場合は、json=payloadまたはdata=json.dumps(payload)を渡します。生の辞書をdata=に渡すとフォームエンコードされます。- API リファレンスに対してフィールド名と型を検証します:
modelは正確にminimax-music-1.5、durationは整数、歌詞の改行は JSON 内で\nに正しくエスケープする必要があります。 - 確信が持てないときは、Python を関与させる前に
curl -d @payload.jsonでリクエストボディ自体が有効かどうかを切り分けます。
タイムアウトと接続エラー
症状: リクエストがハングする、または接続エラーが発生する。
- すべての呼び出しに明示的な
timeoutを設定します。送信タイムアウトはキューの遅延をカバーできる十分な余裕を持つべきですが、レンダリング時間ではありません。 - ポーリングのタイムアウトを全体の
max_waitと等しくしないでください。単一の遅い状態チェックがまだ実行中のジョブを中止すべきではありません。 - 送信が繰り返しタイムアウトするのにポーリングが成功する場合、リクエストボディが大きすぎる可能性があります——歌詞を削減してください。
ポーリングのエラー
症状: ポーリングし続けても finished が現れない、または誤ったリソースをポーリングしている。
- リクエスト ID や相関ヘッダーではなく、送信応答のジョブ識別子を使用していることを確認します。
submitted/runningは「送信をリトライ」ではなく「待機を続ける」とみなします。重複送信は 2 曲目の曲を生成します。- バックオフを入れます。攻撃的なポーリングはレート制限を招き、これは失敗に見えますが自分で作り出したものです。
- ジョブが
failedを報告した場合、再送信の前にメッセージを読みます——無効な歌詞タグや範囲外の長さは毎回同じように失敗します。
行き詰まったときは、生の curl 呼び出しに -v を付けて、実際のステータス行とヘッダーを確認する方に立ち返りましょう。この一手間は、どれだけ Python でデバッグするよりも早く、ほとんどの曖昧さを解消します。