HiAPI 経由で mirelo-sfx-2.0 API を呼び出す方法：curl、Python、非同期ポーリング

mirelo-sfx-2.0 の機能と適用シーン

mirelo-sfx-2.0 は HiAPI 経由で呼び出せるテキスト→効果音モデルです。自然言語の説明——たとえば「重い木の扉がゆっくりと軋みながら開く」や「大理石のテーブルにコインが落ちる」——を渡すと、プロンプトに合致した短いオーディオクリップを生成します。

サンプルライブラリからライセンス取得するのではなく、オンデマンドで効果音を生成したい場合に使うべきエンドポイントです：

• ゲーム・アプリのプロトタイプ開発：インタラクション、UI イベント、環境ループ用の仮または最終効果音を生成します。
• 動画・ポッドキャストのポストプロダクション：スタジオ録音を予約せずに、フォーリー風の音声で空白を埋めます。
• 生成パイプライン：スクリプト、絵コンテ、ユーザー入力からプロンプトを取得し、生成された WAV を出力に付加します。

音の描写が明確で再生時間が短い場合に、このモデルは最も良い性能を発揮します。音楽、音声、長尺オーディオが必要な場合は別のモデルシリーズになります——mirelo-sfx-2.0 は個別の効果音に特化しています。

生成は非同期であるため、ブロッキングな HTTP 呼び出しではなくタスクベースの統合として設計してください。本チュートリアルの残りの部分では、生の curl リクエストから完成した WAV をポーリングで取得する Python クライアントまで、この統合を構築していきます。

前提条件と認証設定

最初の呼び出しの前に、以下を用意してください：

• HiAPI アカウントと API キー。キーは HiAPI コンソールで作成・管理できます。キーはパスワードと同様に扱い、環境変数またはシークレットマネージャーから読み込み、コードリポジトリにコミットしないでください。
• HTTP リクエストを送信するツール。このウォークスルーは curl だけで十分です。コード例は Python 3.8+ を使用します。
• Python の HTTP クライアント。例では簡潔さのため requests を使用しますが、JSON とヘッダーを送信できるクライアントであれば何でも構いません。

HiAPI はすべてのモデルで単一のベース URL と単一の認証方式を使用するため、ここで学ぶ規約は他のエンドポイントにもそのまま当てはまります：

export HIAPI_API_KEY="your-api-key-here"

すべてのリクエストは Authorization ヘッダーでキーを送信します：

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

モデル識別子はリクエストボディで "model": "mirelo-sfx-2.0" として渡します。個別の SDK をインストールする必要はありません——HTTP クライアントが HiAPI のベース URL にアクセスできれば、このモデルを呼び出せます。

実用的なアドバイス：ベース URL は各ファイルにハードコードせず、設定変数に保存してください。ローカルスクリプトからステージングや本番サービスへ移行する際、一箇所だけ変更すれば済むようになります。

curl リクエストのステップバイステップ解説

生成リクエストは、HiAPI のタスク作成エンドポイントへの認証済み HTTP POST です。以下が完全な呼び出しです：

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "重い木の扉がゆっくりと軋みながら開く、古い家の環境音"
    }
  }'

各部分を分解します：

• -X POST——タスク作成は書き込み操作です。このパスに GET を使用してもタスクは開始されません。
• URL——このエンドポイントは新しい生成タスクを受け付けます。ベース URL は HIAPI_BASE_URL に保存されているため、同じコマンドをどの環境でも使用できます。
• Authorization——ベアラートークンはアカウントを識別し、課金の根拠にもなります。ヘッダーの欠落や形式不備は 401 の最も一般的な原因です。
• Content-Type: application/json——リクエストボディは JSON です。このヘッダーがないと、サーバーはペイロードを拒否するか誤って解析します。
• model——mirelo-sfx-2.0 を選択します。HiAPI はこのフィールドに基づいてルーティングするため、URL を変更せずにモデルを切り替えられます。
• input.prompt——音のテキスト記述です。具体的で物理的な描写（素材、動作、環境）は抽象的描写よりも良い結果を生みます。

送信が成功してもオーディオは返りません。識別子（通常は id フィールド）を持つタスクオブジェクトが返り、それを使ってステータスを確認します。レスポンスからその ID を取得してください。それが後で WAV を取得する手がかりになります。

コードに組み込む前にリクエスト構造を確認したい場合は、まずターミナルでこの正確なコマンドを実行してください。成功したら、Python への変換は機械的な作業です。

Python での同じ呼び出し

Python 版も同じ URL、ヘッダー、ボディを維持します——単にそれらを辞書とクライアント呼び出しとして表現するだけです：

import os
import requests

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

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

シェル版との違い：

• 環境へのアクセス——os.environ がシェル展開を置き換えるため、キーがソースコードに現れることはありません。
• -d の代わりに json=——requests が辞書をシリアライズし、コンテンツタイプを設定します。手動ヘッダーは省略できますが、残しても問題ありません。
• raise_for_status()——非 2xx レスポンスを例外に変換します。エラー処理はここに置くべきです。
• timeout——クライアントタイムアウトは、停滞した接続がワーカープロセスをハングさせるのを防ぎます。タスク作成は高速です。長い待機はポーリング中に発生します。

戻り値はタスク ID です。保存してください——それがその生成に対する唯一のハンドルです。ここで Python パスと curl パスが合流します：どちらもオーディオが存在するにはポーリングステップが必要です。

リクエストボディは単なるデータであるため、プロンプトをパラメータ化し、説明のリストを反復して効果音を一括生成できます。各プロンプトに対してタスクを作成し、ID を収集します。

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

音の生成には時間がかかります——ミリ秒ではなく秒単位です——そのため HiAPI はこれをタスクとしてモデル化しています。作成呼び出しはすぐに ID を返し、2 番目のエンドポイントがそのタスクがまだ実行中か、完了したか、失敗したかを報告します。

典型的なループは次のとおりです：

1. タスクを作成し、ID を取得します。
2. その ID でタスクステータスエンドポイントをポーリングします。
3. ステータスがまだ処理中であれば、少し待ってから再度ポーリングします。
4. ステータスが成功を報告したら、レスポンスから出力を読み取ります。
5. ステータスが失敗を報告したら、停止してエラーをスローします。

Python では：

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

特に注意すべき点がいくつかあります：

• ポーリング間隔。2 秒は効果音にとって妥当なデフォルトです。タイトなループでポーリングするとクォータを浪費し、レート制限を引き起こす可能性がありますが、結果が早くなることはありません。
• 全体の締め切り。常にループに上限を設定してください。スタックしたタスクはワーカープロセスを永久にハングさせるのではなく、ジョブを失敗させるべきです。
• ステータス値。未知のステータス値は成功と仮定せず「まだ処理中」として扱い、成功と失敗のステータスで明示的に分岐してください。
• Webhook（提供されている場合）。HiAPI アカウントが完了コールバックをサポートしているなら、サーバー側の本番コードではポーリングよりもそちらを優先してください。スクリプトやプロトタイプではポーリングが依然として最も簡単な選択肢です。

タスク ID はプロンプトと一緒に自身のデータベースに保存し、後で再生成せずにリトライ、監査、出力の再取得ができるようにしてください。

返された WAV レスポンスの読み取り

タスクが成功を報告すると、レスポンスに生成されたオーディオが含まれます。エンドポイントのバージョンによって、出力は WAV ファイルの URL またはインラインのオーディオデータとして現れる場合があります。どちらも「保存可能なバイト列」として扱ってください。

成功したタスクオブジェクトは output などのフィールドの下に出力を保持し、通常はモデル名、元のプロンプト、時間情報などのメタデータも含みます。オーディオ自体は標準の WAV コンテナであり、カスタムデコーダーなしで任意のオーディオライブラリに渡せることを意味します。

URL ベースの結果を永続化するには：

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

オーディオがデコードされたデータとして届く場合は、書き込む前に base64 デコードします：

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

バイト列を取得したら：

• ファイルヘッダーを検証。WAV ファイルは RIFF マジックナンバーで始まります。最初の 4 バイトをチェックすれば、切り詰められたダウンロードがストレージに到達する前に捕捉できます。
• 永続ストレージ。オブジェクトストレージに書き込み、キーをタスク ID と一緒にデータベースに保存します。生成されたオーディオは一時的なレスポンスではなく、キャッシュ可能な成果物として扱ってください。
• 再生または処理。標準ツール——wave、soundfile、または任意のオーディオプレーヤー——でファイルを直接開けます。その後、無音のトリミング、ラウドネスの正規化、配信用の他形式への変換が可能です。

ファイルは通常の WAV であるため、Web エンドポイントやゲームエンジンのアセットパイプラインへの接続に特別な処理は不要です。

よくある失敗ポイントと修正方法

統合の問題のほとんどは、いくつかの予測可能なカテゴリに分類できます。

認証エラー（401 / 403）

401 はほとんどの場合、Authorization ヘッダーが欠落しているか、形式が誤っているか、空の環境変数から構築されたことを意味します。HIAPI_API_KEY がエディタ内だけでなく、プロセスが実行されるシェルでエクスポートされていること、そしてヘッダーが Bearer <key> とスペース 1 つを挟んで記述されていることを確認してください。403 は通常、キーは有効だがそのモデルへのアクセス権がないことを意味します。アカウントのモデル権限を確認してください。

不正な形式のペイロード（400 / 422）

最も一般的な原因は、リクエストボディが有効な JSON でないことです——curl コマンドの引用符の不一致が典型例です。送信前に JSON チェッカーで検証してください。2 番目に一般的な原因は、model フィールドの欠落またはプロンプトのネスト階層の誤りです。モデルはトップレベルの prompt ではなく input.prompt を期待します。最後に、プロンプトが空でなく、モデルドキュメントに規定された制限内の長さであることを確認してください。

ポーリングが頻繁すぎる

スリープなしのタイトな while ループは大量のステータスリクエストを発生させ、レート制限を引き起こし、待機中のタスクを遅くする可能性があります。1〜2 秒の固定間隔を使用し、複数のジョブを並行実行する場合はジッターを加え、常に最大待機時間を強制してください。

作成を完了とみなす

作成レスポンスは成功したように見えて 200 を返しますが、オーディオは含みません。コードがすぐに output フィールドを読み取ると、失敗するか空のファイルを書き込みます。結果に触れる前に、必ずステータスエンドポイントを経由してください。

サイレントタイムアウトとリトライ

タスク作成時のネットワークタイムアウトのリトライは安全ですが、実際には成功したタイムアウト後に作成呼び出しをリトライすると重複ジョブが発生します。エンドポイントが冪等キーをサポートしている場合はそれを使用してください。そうでない場合は、リトライ前に最近のタスクを一覧して照合してください。

ディスクとストレージのエッジケース

WAV バイト列を書き込む際は、バイナリモード（"wb"）でファイルを開いてください。テキストモードはファイルヘッダーを破損します。出力をプロンプト名で保存する場合、同じプロンプトの 2 つのタスクが互いを上書きします——ファイルキーにはタスク ID を使用してください。

これらの防御策があれば、mirelo-sfx-2.0 の統合は短いパイプラインです：作成、ポーリング、永続化。curl 呼び出しから始め、Python に移植し、タスク ID を真実の源としてください。