Mirelo SFX 2.0 API の使い方：5 分で最初の効果音を生成

TL;DR

• 概要：テキストから効果音を生成するモデルで、説明文ひとつで 1〜30 秒の WAV（PCM 16-bit / 48 kHz / モノラル）が得られます。Mirelo SFX 2.0 モデルページを開く で一文書けば試聴できます。Mirelo SFX 2.0 は HiAPI に登場済みで、新規ユーザー登録で 200 クレジットを進呈。
• 料金：出力秒数に応じた課金で 1 秒あたり $0.0215（43 クレジット）、1 秒から。5 秒で $0.1075、30 秒で $0.645。
• 最短の呼び出し方：モデルページで説明文を入力し、長さを選んで送信。製品に組み込む場合は POST /v1/tasks を使い、model に mirelo-sfx-2.0、input には prompt と duration のみを指定します。

Mirelo SFX 2.0 とは

入力は 2 つのフィールドだけ：prompt と duration。説明文は 1〜2,000 文字で、音源・材質・動作・距離と環境を明確に書き、さらにアタックと余韻を補足します。duration は 1〜30 の整数秒で、デフォルトは 5。出力は固定で WAV 1 本、PCM 16-bit、48 kHz、モノラルで、フォーマットの選択肢はありません。

単一の効果音と環境音のみを扱います。1 リクエストにつき 1 つの音響イベントで、楽曲・ボーカル・セリフは生成しません。編集でインパクト音を 1 つ足したい、ゲームに UI フィードバック音が欲しい、ショート動画に雨の夜のアンビエントを敷きたい——そういう用途に向いています。

サイト内のこのハンマー打撃は 1 秒で $0.0215。トランジェントと金属の余響がこの 1 秒に収まっています：

試聴：鋼梁へのハンマー打撃、1 秒 WAV

A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.

このプロンプトで生成 → リンクは説明文を事前入力するだけなので、開いた後に duration を 1 秒に設定して初めてこの音になります。

続いて 10 秒の環境音の事例も聴いてみましょう。同じモデル、同じフィールド構成です：

試聴：雨の夜の金属屋根、10 秒 WAV

オンラインで試す：4 ステップで最初の 1 本を聴く

1. Mirelo SFX 2.0 モデルページ を開きます。登録すると 200 クレジットが付与されます。
2. 説明欄に上のハンマー打撃の説明文を貼り付けるか、自分が欲しい音に置き換えます。
3. duration を 1〜3 秒に設定し、まずアタックと余韻を聴きます。
4. 送信をクリックすると、プレーヤーに WAV が表示され、そのままダウンロードできます。

ステップ 3 は飛ばさないでください。同じ説明文でも 1 秒と 10 秒では別物になります。まず短く、次に長くすることで、繰り返し生成するコストを節約できます。

API 連携：4 ステップで動かす

1. コンソールで API Key を作成します。
2. POST https://api.hiapi.ai/v1/tasks を呼び、model に mirelo-sfx-2.0、input に prompt と duration を入れます。
3. 返ってきた taskId を取得し、callback 通知を待つか、GET /v1/tasks/{taskId} をポーリングします。
4. status が success になったら、output から type が audio の項目を取り、その url で WAV をダウンロードします。

実行可能な curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
      "duration": 1
    }
  }'

返却値のタスク ID は data.taskId にあります：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

この ID でステータスを確認します：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status は queued、handling、success または fail と遷移します。成功時は data.output から type が audio の項目を探します。

Python 版：作成・ポーリング・ダウンロードを一気に書く

import requests
import time

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "mirelo-sfx-2.0",
    "input": {
        "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
        "duration": 1,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    audio_url = next(item["url"] for item in data["output"] if item["type"] == "audio")
    with open("effect.wav", "wb") as f:
        f.write(requests.get(audio_url, timeout=60).content)
    print("saved effect.wav")
else:
    print(data.get("error"))

効果音タスクは動画よりずっと短いので、ポーリング間隔は 2 秒で十分です。3 秒待ち切る必要はありません。

説明文の書き方：5 つの要素

追加パラメータはなく、prompt が制御面のすべてです。以下の 5 つに沿って書けば一発で決まります：

要素	何を書くか	事例での対応する句
音源	何が音を出しているか	a heavy hammer strike
材質	発音体の素材	on a steel beam
動作	どう鳴るか、強さはどうか	single, heavy
距離と環境	聴き手はどこにいるか、空間の広さ	in a large empty warehouse, close perspective
アタックと余韻	始まりの速さ、終わりの長さ	sharp transient, long metallic ring

把握できない次元は省きましょう。「だいたい」「映画っぽく」といった形容詞は書かないでください。説明文の中の具体的な名詞はすべて音に反映されます。「no music and no voices」のような締めの一文は入れておく価値があります。不要なレイヤーを一度に排除できます。

長さの選び方

まず 1〜3 秒で音色・アタック・余韻が正しいか確認し、確定してから duration を目標の長さに引き上げます。同じ説明文でも 3 秒と 10 秒ではイベントの密度が変わります。短い版で方向性を探り、長い版で成品を取る方が、いきなり 30 秒を回すよりずっと安上がりです。

• 打撃・UI・タップ → 1〜3 秒。
• 環境音・アンビエント・部屋の雰囲気 → 10〜30 秒。
• カットの長さに合わせたい → カットの秒数をそのまま整数で記入すれば、モデルは指定した秒数で納品します。

本番前に注意すべき 4 点

1. コールバックにポーリングのフォールバックを。 リクエストボディに "callback": {"url": "https://yourapp.com/webhook", "when": "final"} を追加すると、タスクが終端状態になったときに通知されます。通知は失われる可能性があるので、定期的な GET /v1/tasks/{taskId} で補完しましょう。
2. taskId で冪等化。 success と fail はどちらも終端状態で、同じ taskId の通知を複数回受け取る可能性があります。処理前に DB を確認して重複排除してください。
3. 成果物のリンクは期限切れになります。 output の url は一時アドレスです。取得したらすぐ自分のストレージに転送保存し、長期 CDN としては使わないでください。
4. 1 つの説明文で語るのは 1 イベントだけ。 打撃＋破片の落下、雨音＋雷鳴＋犬の鳴き声などは、複数のリクエストに分けて個別に生成し、後工程で重ねる方が、一文に詰め込むより制御しやすいです。

よくある質問

Mirelo SFX 2.0 は楽曲やボーカルを生成できますか？ できません。単一の効果音と環境音のみで、長さの上限は 30 秒です。BGM には音楽モデル、ナレーションには音声モデルを使ってください。

duration を指定しないとどうなりますか？ 5 秒で生成され、$0.1075 が差し引かれます。別の長さが必要なら 1〜30 の整数で明示してください。

出力を MP3 やステレオにできますか？ できません。固定で WAV 1 本、PCM 16-bit、48 kHz、モノラルです。別形式が必要なら後工程で変換してください。

説明文は最大何文字書けますか？ 2,000 文字です。完全な音響仕様を書き込むのに十分です。

さあ最初の 1 本を生成しよう

上のハンマー打撃の説明文をコピーし、Mirelo SFX 2.0 モデルページを開き、duration を 1 秒に設定すれば、$0.0215 で完全な打撃音を 1 本聴けます。効果を確認したら、同じ 2 つのフィールドを上の curl に入れて、自分のフローに組み込みましょう。完全なパラメータは連携ドキュメントをご覧ください。

関連記事：Mirelo SFX 2.0 の料金 · vs ElevenLabs Sound Effects v2 · 実際の効果音プロンプト 4 選