チュートリアル

HiAPI API で mureka-9.5/instrumental を使用する方法：curl と Python ガイド

Nov 3, 2026

mureka-9.5/instrumental が HiAPI 上で提供する機能

mureka-9.5/instrumental は HiAPI 上のテキストから音楽を生成するエンドポイントで、純器楽の出力に特化してチューニングされています——BGM、ループ素材、アンダースコア、スコアリングなど。プロンプトで曲を記述し、単一のタスクを送信すると、HiAPI が完成した音声リソースを返します。それをダウンロードしてゲーム、動画編集、ポッドキャスト、製品デモに組み込めます。

instrumental（器楽）という言葉が鍵です。このエンドポイントはリードボーカルの歌唱がない音楽を対象としているため、ナレーションやセリフを明瞭に聞き取れる状態に保つ必要がある場面に適しています。歌詞付きの歌唱トラックが必要ならそれは別の話であり、ボイスオーバーの下にクリーンなBGMを敷きたいなら、これが正しいツールです。

次の場合にこのエンドポイントを選択してください：

音楽ライブラリから素材を取るのではなく、生成したBGMが欲しい。
一度きりのカスタム依頼ではなく、多数のバリエーションを高速かつプログラム的に生成したい。
パイプラインがすでにHTTPを使用しており、音楽を他のリソース生成ステップと同様に扱いたい。
予測可能なリクエスト形態（送信、ポーリング、ダウンロード）を重視する。

他の音楽生成エンドポイントと同様、処理は非同期です。送信するとタスクが返り、音声が生成されるまでそれを追跡する必要があります。最初からこの点を中心にコードを設計すれば、残りの統合作業は定型作業になります。

製品内での位置づけ

典型的な利用者は、オンデマンドで曲を必要とするコンテンツパイプラインです。例えば、各クリップの下に音楽を敷きたい動画レンダラー、アンビエントループ素材を求めるゲーム、ユーザーがムードを入力すると結果を聴けるプロトタイピングツールなどです。このエンドポイントはテキスト駆動なので、既存のメタデータ——ジャンル、リズム感、ムード、想定尺——でプロンプトをテンプレート化し、レンダリング時に生成できます。

各リクエストは独自のライフサイクルを持つ生成タスクとして扱ってください。この枠組みが、リトライロジック、ログ記録、コスト計算を健全に保ちます。

リクエスト送信前の準備

最初の呼び出しが成功する前に、いくつかの条件を満たす必要があります。どれも複雑ではありませんが、1つでも欠けると初回リクエスト失敗の最も一般的な原因になります。

認証情報

HiAPI API キーが必要です。機密情報として扱ってください：HIAPI_API_KEY のような環境変数から読み込み、提出するスクリプトにハードコードせず、漏洩したらローテーションしてください。キーは Authorization ヘッダーで bearer トークンとして送信します。

export HIAPI_API_KEY="your_api_key_here"

エンドポイントとトランスポート

HiAPI の統一 API 経由で mureka-9.5/instrumental モデルを呼び出します。ベース URL は HiAPI API ホストで、モデル識別子は HiAPI がこのエンドポイント向けに記録した規約に従い、リクエストペイロードまたはパスに置きます。HTTPS を使用し、Content-Type: application/json を送信し、JSON 本文を送信してください。

パラメーター名を推測しないでください。HiAPI はこのモデルが受け付けるフィールドを記録しています。その集合以外のものは、最良でも無視され、最悪では拒否されます。欲しいフィールドがドキュメントにないなら、それは契約の一部ではありません——既にあるものに基づいて構築してください。

準備するもの

音楽を記述するプロンプト：ジャンル、楽器編成、ムード、リズム感、想定用途。
モデルが公開している、ドキュメント化された尺またはバリエーションのオプション。
タスク識別子を保存し、後でダウンロード URL を保存する場所。
コード実行場所から HiAPI ホストへのネットワークアクセス。

時間に関する注意

生成は即時ではありません。クライアントのタイムアウトを緩めに設定し、ポーリングが必要になることを想定してください。同期思考——リクエストを送って同じレスポンスで音声が返るまでブロックする——は不安定なコードを生みます。

動作する curl リクエスト

curl から始めましょう。あなたと HTTP の対話の間のあらゆる層を取り除くので、問題があればすぐに分かります。

呼び出し

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "warm lo-fi hip hop instrumental, mellow electric piano, soft vinyl crackle, relaxed 80 bpm, no vocals"
    }
  }'

まずこの2つの環境変数を設定してください。そうすれば、あなたが選んだ内容以外に機密情報が平文でシェル履歴に残ることはありません：

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # 使用該端点有文档记录的路径
export HIAPI_API_KEY="your_api_key_here"

各部分の役割

-X POST — 送信は作成操作です。
-H "Authorization: Bearer ..." — あなたのアカウントで呼び出しを認証します。
-H "Content-Type: application/json" — 本文が JSON であることをサーバーに伝えます。省略すると、多くのサーバーは本文をそのまま拒否します。
-d '{...}' — JSON ペイロード。model フィールドでエンドポイントを指定し、input オブジェクトがプロンプトやその他のドキュメント化されたフィールドを保持します。
-sS — 進行状況を抑制しつつ、エラーは表示します。スクリプトで便利です。

レスポンスの読み取り

レスポンスは JSON です。タスクまたはジョブの識別子とステータスフィールドを探します。確認しやすいように整形して出力してください：

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

識別子を保持してください。それが以後のすべてのステータス確認のハンドルになります。レスポンス本文全体をアプリに解析させず、タスク ID とステータスを抽出し、デバッグ用に生のレスポンスを保存してください。

2xx 以外のステータスが返ったら、本文を読んでください——HiAPI は構造化されたエラーメッセージを返し、通常は問題のあるフィールドを指摘します。

Python での同じリクエスト

Python 版は curl 呼び出しに正確に対応します：同じヘッダー、同じ JSON 本文。簡潔さのために requests を使うか、依存ゼロにしたければ標準ライブラリを使ってください。

requests を使う

import os
import requests

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

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "warm lo-fi hip hop instrumental, mellow electric piano, "
            "soft vinyl crackle, relaxed 80 bpm, no vocals"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # ドキュメント化されたフィールド名を使用
print("submitted:", job_id, data.get("status"))

標準ライブラリを使う

依存を追加できない場合：

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

実用的な習慣

timeout=30 は送信時のみに使用してください。ポーリングには独自のループと独自のタイムアウトが必要です。
解析前に raise_for_status() を呼び出してください。エラーレスポンス本文はタスクではありません。
タスク ID の抽出を小さなヘルパー関数にまとめておけば、フィールド名の変更は1行の修正で済みます。
API キーを絶対にログに記録しないでください。代わりにタスク ID とステータスを記録してください。
ペイロードをコード内の辞書として保持し、一度だけシリアライズして、テストがそれに対してアサートできるようにしてください。

非同期タスクの処理とポーリング

送信は最初のステップです。生成はサーバー側で行われ後で完了するため、タスクが終了状態を報告するまでステータスエンドポイントをポーリングします。

ループの形

タスクを送信し、ID を取得する。
短時間スリープする。
その ID のステータスを照会する。
ステータスがキュー中または処理中なら、バックオフして繰り返す。
ステータスが成功状態なら、出力を読む。
ステータスが失敗状態なら、エラーを記録して停止する——盲目的にリトライしない。

信頼できる実装

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # ジッター
        delay = min(delay * 1.5, max_delay)          # 指数バックオフ

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

各詳細が重要な理由

ジッター（Jitter）は、複数のタスクが並行実行されているときに同期したリトライを防ぎます。
バックオフ（Backoff）は、曲のレンダリング中にステータスエンドポイントを叩き続けるのを防ぎます。
期限（Deadline）は、無限のハングをパイプラインが処理できるクリーンな例外に変換します。
終了状態のチェックは HiAPI のドキュメントに記録されたステータス文字列に一致させるべきです。推測を信じず、API リファレンスで確認してください。
リトライは一時的なネットワークエラー（タイムアウト、5xx）に対して行うべきで、すでに検証エラーで失敗したタスクに対して行うべきではありません。

運用のヒント

ポーリングを開始する前に job_id を永続化してください。プロセスが死んでもポーリングを再開でき、2回目の生成に料金を払わずに済みます。タイムスタンプ付きのステータス遷移を記録すれば、どこに時間がかかっているか分かります。多数のタスクを実行する場合は、各タスクにリクエストスレッドをブロックさせるのではなく、キュー経由で少数のタスクを並行ポーリングしてください。

器楽出力の取得とダウンロード

器楽モードはリクエストで表現され、このエンドポイントはそのような出力専用です。実際には、プロンプトの文言がこれを強化します：楽器を名指しし、ムードを描写し、ボーカルなしを明言してください。ボーカルラインを要求するプロンプトはエンドポイントの目的と矛盾します。

音声が現れる場所

タスクが成功状態に達すると、ステータスレスポンスが結果を運びます。音声はステータス JSON 内の base64 ではなく、別途取得する URL として配信されることを想定してください。レスポンスを読み、ドキュメント化された出力フィールドからダウンロード URL を抽出します。

result = wait_for_job(job_id, status_url, headers)
# 最初の数回は結果を注意深く確認し、その後フィールドを固定する。
audio_url = result["output"]["audio_url"]   # API リファレンスでフィールド名を確認

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

ダウンロードの習慣

ストリームでディスクに書き込む。音楽ファイルは大きいので、メモリに完全に読み込むのは避けるべき負荷です。
コンテンツタイプを確認する。レスポンスが示す拡張子でファイルを保存し、ハードコードされた拡張子は使わないでください。
URL は一時的なものとして扱う。速やかにダウンロードするか、ドキュメントで安定していると説明されている場合のみ URL を永続化してください。永続保存にはバイトを自分のストレージにコピーしてください。
一度だけ取得する。完了マーカーなしでリトライループ内でダウンロードすると、部分ファイルを簡単に作ってしまいます。一時名で書き込み、成功後にリネームしてください。
出所を記録する。タスク ID とプロンプトをファイルと一緒に保存してください。後でバリエーションが必要になったとき、正確な入力が手元にあります。

よくある失敗点と修正

初回統合の問題のほとんどは短いリストに収まります。以下がチェックリストです。

401 / 403 — 認証。ヘッダーが間違っている、キーが欠けている、または環境変数が空文字列に解決されている。キーがコードを実行する同じシェルまたはプロセスで設定されていること、ヘッダーが正確に Authorization: Bearer <key> と読まれていることを確認してください。

400 — ペイロードの形式エラー。model の欠落、mureka-9.5/instrumental のタイプミス、無効な JSON、またはエンドポイントが受け付けないフィールド。まず curl で本文を送信し、ペイロードをコードから切り離してください。送信前に JSON を検証してください。末尾のカンマが定番の問題です。

415 または空本文エラー — コンテンツタイプ。Content-Type: application/json が必須です。一部の HTTP クライアントは json= を渡すと自動設定しますが、すべてではありません。

ポーリングのタイムアウト。期限が短すぎる、バックオフが攻撃的すぎる、またはタスクが実際に失敗しているのに実行中と分類している。正確なステータス文字列をドキュメントで確認し、デバッグ時は毎回のステータス遷移を出力してください。

ダウンロード URL の欠落。間違ったフィールドを読んでいる、またはタスクが終了成功状態に達する前にレスポンスを読んでいる。成功ペイロード全体を一度記録し、音声 URL のパスを確認してから固定してください。

重複生成。ポーラーがクラッシュし、何かが再送信した。ポーリング前にタスク ID を永続化し、新しいタスクを送信する前に既存タスクを確認してください。

レート制限。429 レスポンスにはジッター付きでバックオフし、多数のスレッドから同時に爆発させるのではなく、作業をキューに入れてください。

この順序で対処してください——認証、ペイロード、コンテンツタイプ、ポーリング、出力——そうすれば通常は一度で原因が見つかります。curl 呼び出しとその Python 版の両方がエンドツーエンドで成功すれば、エンドポイントはあなたの要求どおりに動作しています：プロンプトを器楽曲に変換し、ダウンロード URL を返します。

すべての記事を見る →