hiapi API で lyria-3-pro を使う方法：curl、Python、実行可能なリクエスト例

lyria-3-pro は hiapi API から提供される音楽生成モデルです。テキストプロンプトを送ると、1本の完成した音声トラックが得られます。このガイドでは、実際に taskId が返ってくるリクエストの流れを順に説明し、完全な（とても短い）入力 schema と、使い捨てのテストを超えた後に必要になる本番環境の詳細を解説します。

準備するもの

• hiapi の API key。コンソールから取得できます。key は sk- で始まります。
• curl または Python の requests。SDK は不要です。hiapi は標準 REST を使用します。

lyria-3-pro は hiapi の統一非同期タスク API 上で動作します。タスクを POST するとすぐに taskId が返り、その後で結果をポーリングするか、音声トラックの準備ができたときにコールバックを受け取ります。

最小の実行可能な例

1. タスクを作成する

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

正常なレスポンスは、音声トラックが実際にレンダリングし終える前に即座に返ります：

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

2. 結果をポーリングする

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

最初のポーリングの前に数秒待ち、その後は 3〜5 秒ごとに確認してください。status は archiving などの途中状態を経て、最終的に終端状態に入ります：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

output[0].url はできるだけ早くダウンロードしてください。デフォルトの temp ストレージ層は約 7 日後に失効します（expireAt は Unix タイムスタンプです）。失敗時は status が fail になり、output の代わりに data.error に { code, message } が含まれます。

3. Python での同じリクエスト

import time
import requests

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

payload = {
    "model": "lyria-3-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

完全な入力 schema

input はちょうど 2 つのフィールドだけを受け付けます。この一覧以外のものはすべて拒否され、400 INVALID_REQUEST が返ります：

フィールド	型	必須	説明
prompt	string	はい	ジャンル、編成、ムード、テンポを記述します。具体的であるほど、結果が一貫します。
seed	integer	いいえ	最小値は 0。同じ prompt に対して同じ seed を再利用すると、より再現性の高い結果が得られます。

prompt は必須です。省略するとタスクは作成されません：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

それ以外のフィールドを送ると（duration、negative_prompt、sample_count、および一部の他の音楽モデルが受け付ける同様のフィールド）、リクエストはそのまま拒否されます：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

出力される音声トラックの長さはモデル自体によって固定されています。duration パラメータで設定することはできません。

本番環境での注意点

ポーリングよりコールバックを。 素早いテスト以外では、ループでポーリングする代わりにトップレベルの callback を渡してください：

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

タスクが終端状態（success または fail）に達すると、hiapi は callback.url に 1 回の POST を送信します。ポーリングループを開いたままにする必要はありません。ただし、コールバックの配信に失敗する場合に備えて、フォールバックとしてポーリングも残しておくべきです。

冪等性。 呼び出し元が同じリクエストを再試行する可能性がある場合は、Idempotency-Key ヘッダー（最大 255 バイト）を送信してください。同じアカウントで同じ key を使った再試行は、元の taskId を返し、重複した音声トラックを作成（および課金）することはありません。

出力を 7 日を超えて保持する。 出力ストレージはデフォルトで temp（約 7 日）です。作成時にトップレベルの "storage": "persistent" を設定すると、音声トラックを長期保存できます（サイズに応じて課金）。または、後から temp の出力を昇格することもできます。

エラー処理。 無効または未承認の key は HTTP 401 を返します：

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

不正な形式の入力は 400 を返し、error_code: INVALID_REQUEST が付きます（上記のとおり）。残高不足は 402、JSON 以外の Content-Type は 415 を返します。断続的な 503 が発生した場合は、バックオフして再試行してください。これはプラットフォームが一時的に利用できないことを意味し、リクエストに誤りがあるわけではありません。

lyria-3-pro（およびプラットフォーム上の他のすべてのモデル）の価格は、hiapi の料金ページに掲載されており、ここにハードコードされていません。プランが変更される可能性があるためです。

関連リソース

• lyria-3-pro モデルリファレンス — このモデルの料金とプレイグラウンド。
• タスクの作成 / タスク詳細の取得（統一非同期 API） — hiapi 上のすべてのモデルが使用する共通のリクエスト/レスポンス契約。
• minimax-music-3 API：curl と Python ガイド — もう一つのテキスト-to-音楽モデルで、出力スタイルの比較に使えます。
• MiniMax Music API の使い方（minimax-music-1.5） — より初期の MiniMax 音楽生成モデルで、コスト/品質の比較に適しています。

よくある質問

生成する音声トラックの長さは設定できますか？ いいえ。lyria-3-pro の input schema は prompt と seed のみを受け付けます。duration フィールドはなく、音声トラックの長さはモデルが独自に決定します。

lyria-3-pro はネガティブプロンプトやスタイル参照音声をサポートしていますか？ いいえ。プラットフォーム上の他の一部のモデルとは異なり、lyria-3-pro の schema は厳密に prompt と seed のみです。negative_prompt や参照音声のフィールドを送ると 400 INVALID_REQUEST が返ります。

出力ファイルの形式は何ですか？ MP3 で、output[0].url として返され、type は "audio" です。この URL は一時リンクで、"storage": "persistent" を設定しない限り output[0].expireAt に従って失効します。

再現可能な結果を得るにはどうすればよいですか？ 同じ prompt を使い、同じ seed（非負の整数）を渡してください。seed を省略すると、呼び出しごとに異なる結果が生じる可能性があります。

400 を返し続けるリクエストをデバッグする最速の方法は？ message を読んでください。具体的にどのフィールドが欠落しているか、または無効であるかが示されます。schema は厳格です。このモデルが受け付けないフィールド（たとえばプラットフォーム上の他の音楽モデルが実際に受け付ける duration）を送ると、"additional properties not allowed" エラーを伴う 400 が返ります。