HiAPI 上の ElevenLabs Music API：curl、Python、プロンプトレシピで音楽を生成する

なぜ HiAPI 経由で elevenlabs/music-v2.5 を呼び出すのか

製品に音楽生成機能を追加する場合、最速の道は必ずしも最もクリーンな道ではありません。バックエンドをモデルプロバイダーに直接接続するということは、そのプロバイダーのアカウント設定、認証方式、リトライのセマンティクス、リクエスト構造を自分で管理する必要があるということです。新しいモデルを採用するたびに、そうした意思決定が一組増え、実験のたびに統合ブランチが残ります。

HiAPI 経由で elevenlabs/music-v2.5 を呼び出すと、この作業の形が変わります。必要なのはベース URL 一つ、認証ヘッダー一つ、そしてモデルを切り替えても安定したリクエストの取り決めだけです。モデル識別子（elevenlabs/music-v2.5）はリクエストボディ内の単なる文字列なので、音楽モデル間の切り替えや、比較のために2つ目のモデルを試すことも、新しい SDK をインポートするのではなく1行の変更で済みます。

統合方法を選ぶ開発者にとって、注目すべき実用的な利点は3つあります：

• 統一された認証情報の管理面。 キー管理、ローテーション、環境分離（開発/ステージング/本番）がプロバイダーごとに倍増するのではなく、一箇所に集中します。
• 移植可能なリクエストパターン。 以下の curl と Python のスニペットは、HiAPI 上で他のモデルを使うときのものと一致しています。パターンを一度学べば十分です。
• 使用量が一箇所に集約。 音楽生成は出力の長さに応じて課金されるため、他のモデルの使用量と同じ場所に置くことで、散在する請求書ではなく単一のダッシュボードでコストを追跡できます。

代償は抽象化レイヤーを経由するため、プロバイダー固有の癖が正規化されることです。初回の統合やほとんどの本番ユースケースでは、この正規化こそが望ましいものです。モデルの具体的な挙動を理解する必要があるときは、サイト上の詳細ページが信頼できる情報源です。

最初の音楽リクエストの前に

コードを書く前に4つのことを確認しましょう。そうすれば最初の呼び出しで 401 や検証エラーではなく、音声が返ってきます。

1. API キー

HiAPI アカウントから API キーを取得する必要があります。他のあらゆるキーと同様に扱いましょう：環境変数に保存し、ソースにコミットせず、ローカル開発と本番で別のキーを使うことで、一方を無効化しても他方に影響を与えずに済みます。

export HIAPI_API_KEY="your_key_here"

2. ベース URL とエンドポイントの取り決め

すべてのモデル呼び出しは同じベース URL を通り、モデルはパス内ではなくリクエスト内部で識別されます。プロジェクトにベース URL の定数を保持しておけば、環境が異なる場合でも一箇所を変更するだけで済みます。

3. 自然言語で書かれたプロンプト

elevenlabs/music-v2.5 は、欲しい音楽を説明するテキストプロンプトを受け取ります。楽譜や MIDI ファイルは不要です。ジャンル、編成、ムード、想定される長さを1〜2文で指定すれば始められます。後のセクションで再利用可能なレシピを紹介します。

4. 出力に対する正しい期待

音楽生成が返すのは音声であり、JSON の楽譜ではありません。レスポンスペイロードの扱いを計画しましょう：開発中はファイルに書き出し、本番ではストリーミングまたは保存します。クリップをどのくらいの長さにするかを事前に決めておきましょう。長さはリクエストにも課金にも影響します。

最初のリクエストの前にもう一つ：仮定をコードにハードコードするのではなく、サイトの料金パネルで elevenlabs/music-v2.5 の現在のレート制限と価格を確認しましょう。価格や制限は変わるため、統合側はそれらをスクリプトに埋め込んだ定数ではなく設定として読み込むべきです。

curl で最初の呼び出しを行う

curl から始めましょう。なぜなら、あなたと HTTP リクエストの間のすべてのレイヤーを取り除いてくれるからです。curl の呼び出しが成功すれば、アプリ内での失敗は API ではなくアプリ自身の問題です。

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

各部分の役割は以下の通りです：

• -sS は進捗出力を静かにしつつ、エラーは表示します。出力をファイルに貼り付けるときに便利です。
• URL は統一エンドポイントです。モデル名がパスに現れず、リクエストボディに現れる点に注意してください。
• Authorization: Bearer $HIAPI_API_KEY は環境からキーを読み取るので、シェル履歴に平文で残りません。Windows では、set または PowerShell の $env: 構文で変数を設定してください。
• Content-Type: application/json は必須です。このエンドポイントはフォームエンコードを受け付けません。
• model は正確な識別子 elevenlabs/music-v2.5 です。ここでのタイプミスは汎用的な失敗ではなくモデル未検出エラーになるため、デバッグに役立ちます。
• messages はプロンプトをユーザーメッセージの内容として渡します。プロンプトは1つのメッセージに入れましょう。長く構造化されたプロンプトは、複数に分散させるよりも効果的です。

レスポンスボディには生成された音声とリクエストに関するメタデータが含まれます。開発中は出力をファイルにリダイレクトして、結果をすぐに試聴できるようにしましょう：

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

ペイロードを request.json に入れて -d @request.json で読み込むのは、早いうちに身につけるべき習慣です。リクエストが比較・レビューしやすくなり、一度に1つのパラメータだけを変えて再実行しやすくなります。

Python で同じ呼び出しを再現する

curl の呼び出しが音声を返したら、それを Python に移植しましょう。目標は単に動くスクリプトではなく、タスクキュー、API ハンドラー、ノートブックからコピペのずれなく呼び出せる関数です。

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """HiAPI 経由で elevenlabs/music-v2.5 に音楽プロンプトを送信する。"""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

関数が成長するにつれて、維持すべき判断がいくつかあります：

• 標準ライブラリを優先する。 urllib はチュートリアルでの依存関係の変動を避けます。プロジェクトがすでに requests や httpx を使っているなら、変換は機械的です：json=payload、headers=headers、timeout を渡すだけです。
• タイムアウトは必須。 音楽生成はチャット補完よりも時間がかかります。デフォルトに頼らず明示的なタイムアウトを設定しましょう。リクエストする最長クリップの想定生成時間より長い値を選びます。
• キーは呼び出し時に読み取る（インポート時ではなく）。そうすれば同じモジュールがローカルでも、実行時に環境を注入するコンテナでも動作します。
• 構造化データを返す（文字列を出力するのではなく）。音声をディスクに書き出すか、オブジェクトストレージにアップロードするか、クライアントに転送するかは呼び出し側が決めます。

何かを構築する前に、Python 関数と curl 呼び出しが同じプロンプトに対して等価な結果を生み出すことを確認しましょう。この一貫性が回帰のベースラインになります。

スタイル・感情・長さのプロンプトレシピ

音楽プロンプトは、3つの質問に順番に答える形が最も効果的です：どのジャンルと編成か、どんな感情的トーンか、どのくらいの長さか。曖昧なプロンプトは汎用的な出力を生み、長すぎるプロンプトは重要な記述子を薄めてしまいます。目標は、密度の高い1文、または3つの短い節です。

これらをコピー＆ペースト可能な出発点として使い、一度に1つの次元だけを調整しましょう。

スタイル主導のレシピ

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

感情主導のレシピ

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

長さ主導のレシピ

長さはプロンプト内に明確な目標として書き、編曲と一致させるべきです。ゆっくりした導入と長い終奏を伴う15秒のリクエストは、唐突に切り捨てられます。

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

組み合わせ例

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

出力が期待に合わないとき

試行ごとに1つの変数だけを調整しましょう。そうすれば何が結果を変えたのかが分かります。

• 汎用的すぎる： 感情を表す言葉を具体的な編成やテンポで置き換えましょう。「Energetic」は「driving 16th-note bass at 128 BPM」ほど強力ではありません。
• 忙しすぎる、または雑然としている： ポジティブな記述子を追加するのではなく、楽器を明示的に除外しましょう（no drums、no vocals、sparse arrangement）。
• 長さが合わない： クリップが突然終わるなら、より短い目標と明確な終わりを要求しましょう。急ぎ足に感じるなら、要求するセクションの数を減らしましょう。
• スタイルの漂流： ジャンルと編成をプロンプトの前方に移動させましょう。前方のトークンの方が重みが大きくなります。

リポジトリに小さなプロンプトファイルを保持し、有効なレシピを記録しましょう。このファイルは、生成された個々のクリップよりも価値があります。なぜなら、プロンプト作成を再現可能なエンジニアリング成果物に変えるからです。

よくあるエラーと修正方法

ほとんどの初回統合は、いくつかの予測可能な方法で失敗します。推測を始める前に、このチェックリストを確認しましょう。

認証の失敗

401 はほぼ常に、リクエストヘッダーの形式が誤っているか、プロセスの環境にキーがないことを意味します。Bearer の後に余分なスペースがないか、キーが間違った .env ファイルから読み込まれていないか、あるいは export がスクリプトを実行するのとは別のセッションで実行されていないかを確認しましょう。キーの長さ（キー自体ではなく）を出力して、値が入っていることを確認します。

モデル識別子の不一致

モデル未検出や検証エラーは通常、model 文字列が完全一致していないことを意味します。elevenlabs/music-v2.5 は大文字小文字を区別し、スラッシュを1つ含みます。チャットウィンドウからコピーした場合は、スマートクォートや改行の残骸がないか確認しましょう。

リクエストボディの形式エラー

curl は動くのに Python が動かない場合、その違いはほぼ常にシリアライズの問題です。JSON 文字列を期待する場所に Python の dict をそのまま渡す、json.dumps で二重エンコードする、Content-Type: application/json を忘れる——いずれも、真の原因とは無関係に見えるサーバー側のパースエラーを生み出します。コードが送信する正確なリクエストボディをログに出力し、動作する curl のペイロードと1文字ずつ比較しましょう。

長いクリップでのタイムアウト

長い長さは長い生成時間を必要とします。チャットリクエストに適したクライアントのタイムアウトは、長い音楽リクエストを途切れさせてしまいます。このエンドポイント専用にタイムアウトを引き上げ、リトライは接続レベルの失敗にのみバックオフ付きで追加しましょう。すでに課金された可能性のあるリクエストを盲目的にリトライしてはいけません。

プロンプトの長さと内容

極端に長いプロンプトや、API 自体に関する指示を含むプロンプトは、しばしばより悪い音楽を生みます。プロンプトは音楽についてのみにしましょう。昨日は有効だったプロンプトが動かなくなったら、スタイル/感情/長さの骨組みに簡略化してから再構築しましょう。

レスポンスをテキストとして扱う

このエンドポイントは音声データを返し、読める文字起こしテキストは返しません。生のレスポンスボディを .txt ファイルに書き込み、なぜ再生できないのかと首をかしげるのは初日によくあるミスです。正しい音声拡張子で保存し、さらに構築を進める前にファイルがプレイヤーで開けることを確認しましょう。

エラーが本当に不明瞭なときは、可能な限り最小の curl リクエストで再現しましょう。これにより、問題が API の契約にあるのか、あなたのコードにあるのかを切り分けられます。

テスト呼び出しから再現可能なワークフローへ

成功したテスト呼び出しは出発点であり、統合ではありません。このチェックリストを使って、チームが依存できるものに変えましょう。

• 設定を外に出す。 ベース URL、モデル識別子、タイムアウト、デフォルトの長さ目標は、散在する文字列リテラルではなく設定に置きましょう。環境固有の値は環境から取得します。
• クライアントを集中化する。 リクエストは1つの関数または軽量なクライアントクラスが担当します。どのモジュールも音楽エンドポイントへの HTTP 呼び出しを自前で構築すべきではありません。そうでなければ、ヘッダーやエラー処理で食い違いが生じます。
• カテゴリ別にエラーを処理する。 認証、検証、タイムアウト、サーバーエラーを区別します。一時的なエラーのみをバックオフと上限付きでリトライしましょう。すでに出力を生成して課金された可能性のあるリクエストをリトライしてはいけません。
• 音声を正しく保存する。 決定的なキーでオブジェクトストレージに書き込み、プロンプトを生成されたアセットと一緒に置き、モデル識別子を記録します。後で結果を再現するには、そのときに何をリクエストしたかを正確に知る必要があります。
• 長さを一級のパラメータとして追跡する。 課金は出力の長さに従うため、プロンプトテンプレートで目標の長さを明示し、リクエストごとに記録して、コストレポートが使用量と一致するようにしましょう。
• プロンプトライブラリを構築する。 検証済みのレシピをバージョン管理下に置き、各レシピの用途を短く記録しましょう。新しいチームメンバーは推測ではなく、動作するプロンプトから始められます。
• 同期パスと非同期パスを分離する。 生成は遅くなることがあります。ユーザー向け機能では、ジョブを投入し、リクエストを永続化し、ワーカーにモデルを呼び出させましょう。HTTP ハンドラーが生成の間ずっと開いたままになるべきではありません。
• スモークテストで検証する。 固定の短いプロンプトを送信し、音声レスポンスの形式が正しいことをアサートするテストは、認証情報や契約のドリフトを早期に発見できます。

パラメータと制限について深く知る準備ができたら、HiAPI 上の elevenlabs/music-v2.5 モデルページが、仮定をハードコードする前に現在の能力を確認する場所です。