hiapi API で lyria-3.5 を使う方法：curl、Python と動作するリクエスト

lyria-3.5 は hiapi のテキストから音楽を生成するモデルです。音楽の説明、歌詞、またはその両方を送信すると、完成したトラックが得られます。さらに任意でタイトル、テンポのヒント、長さの制御も指定できます。このガイドでは、入力 schema、実際にトラックを返すリクエスト、そして一度きりのテストから本番運用に必要な詳細までを完全に解説します。

必要なもの

• hiapi の API key。dashboard で取得できます。key は sk- で始まります。
• curl または Python の requests。SDK は不要です。hiapi は純粋な REST を使用します。

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

完全な入力 schema

lyria-3.5 は単なる裸の prompt 以上のものを受け付けます。prompt または lyrics の少なくとも一方を必ず提供する必要がある以外は、すべてのフィールドが任意です：

フィールド	型	説明
prompt	string	ジャンル、楽器、ムード、ボーカル、曲の構成。prompt または lyrics を提供します。
lyrics	string	1 行につき 1 文。セクションタグ——[Intro]、[Verse]、[Chorus]、[Bridge]、[Outro]——はそれぞれ単独の行に置き、その後に歌詞を続けます。繰り返しセクションは [Verse 1]、[Verse 2] のように番号を振ります。
title	string	生成される曲のタイトル。
bpm	string	テンポのヒント。数字の文字列である必要があります（例："90"）。
length	integer	リクエストする長さ（秒）で、1〜240。長さのヒントとして使われ、実際の長さは異なる場合があります。省略すると指定なしになります。
seed	string	数字文字列のシード（例："00123"）。seed が同じでも、まったく同じ音声が得られる保証はありません。

事前に注意すべき点が 2 つあります。bpm と seed は数字ではなく文字列です——90 ではなく "90" を送信してください。そうしないと API は 400（got number, want string）を返します。また schema は厳格です。上表にないフィールド（duration、style、genre、negative_prompt など）は additional properties '...' not allowed として 400 を返します。

最小の動作例

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.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

正常な応答は、トラックが実際にレンダリングされる前にすぐ返ります：

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

2. 結果のポーリング

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

最初のポーリングの前に数秒待ち、その後は 3〜5 秒ごとに確認します。status はまず handling を経て、やがて終状態になります。以下は上記リクエストの約 100 秒後の実際の応答です：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

出力のコンテナ形式はリクエストによって異なる場合があります（ここでは .m4a、hiapi の他の音楽モデルは .mp3 を返します）——拡張子を決め打ちせず、output[0].type と URL を読み取ってください。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.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

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

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

純粋なインストゥルメンタルが必要か、ボーカル入りのトラックが必要かに応じて、lyrics を prompt に置き換えてください（または両方を送信してください）。

本番環境での注意点

• ポーリングの代わりにコールバックを使う。トップレベルの callback オブジェクトを追加します：{"url": "https://yourapp.com/hook", "when": "final"}。when は "final" のみを受け付けます。進捗更新ではなく、タスクが終状態になったときに 1 回だけ呼び出しを受け取ります。
• 冪等性。タスク API はクライアント提供の冪等キーを受け付けません。そのためアプリケーション層でリトライの問題を防いでください。taskId を受け取ったらすぐに永続化し、リトライ前にタスク状態を確認して重複リクエストを避けます。
• エラー。API key が欠落または無効な場合は HTTP 401 と error_code: "permission_denied" が返ります。schema 違反の場合は HTTP 400 と error_code: "INVALID_REQUEST" が返り、メッセージで問題のあるフィールドが示されます。これにより、本番投入前に余分な duration や数値型の bpm を発見できます。
• ストレージ。ポーリング成功またはコールバック受信後、すぐに output[0].url を自身のストレージへ移してください。temp 層が expireAt を超えて保持されることを当てにしないでください。

関連記事

• lyria-3-pro API チュートリアル——hiapi のもう 1 つの Lyria モデル。歌詞やテンポ制御が不要なら、prompt だけで済むよりシンプルな schema です。
• MiniMax Music API ガイド——hiapi 上のもう 1 つのテキストから音楽を生成するモデルで、独自の歌詞とサンプリングのオプションがあります。
• lyria-3.5 モデルリファレンス——正式なパラメータドキュメント。
• hiapi の料金——各モデルの現在の料率。

FAQ

prompt と lyrics の両方を送る必要がありますか？いいえ——API は少なくとも一方を提供することだけを要求します。prompt だけならインストゥルメンタルのトラック、lyrics だけなら歌詞に完全に駆動されたトラック、両方ならその組み合わせになります。

lyria-3.5 はどの音声形式を返しますか？リクエストによって異なります——output[0].type と URL の拡張子を確認し、.mp3 や .m4a と決め打ちしないでください。

正確なテンポを強制できますか？bpm はヒントであり、厳密な制約ではありません。また文字列で送信する必要があります（90 ではなく "90"）。

生成されるトラックの長さはどのくらいですか？length は 1〜240 秒を受け付けますが、モデルへのヒントにすぎず、正確な長さは保証されません——返されたファイルの実際の再生時間を確認してください。

同じ seed なら 2 回とも同じトラックが得られますか？いいえ。seed は数字文字列で生成結果を微調整するものですが、hiapi のドキュメントは音声が完全に同一になる保証はないと明記しています。

genre や duration のような認識できないフィールドを送るとどうなりますか？schema は厳格です——そのフィールドが黙って無視されるのではなく、400 と additional properties '<field>' not allowed が返ります。