Skip to content
PleumRouter
始める

音楽生成

Lyria 3 でプロンプトからオーディオクリップを生成する非同期ジョブ API です。

音楽生成はテキストや画像と異なり非同期ジョブとして動作します。送信は 202 Acceptedで即座に返り、ジョブをポーリングし、成功すると 事前署名 URL でオーディオをダウンロードします。音声合成（TTS）・文字起こし（STT）は /v1/audio/speech・/v1/audio/transcriptions を参照してください。

送信#

POST/v1/audio/generations
curl
curl https://apirouter.pleum.ai/v1/audio/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3-clip-preview",
    "prompt": "Upbeat k-pop synth riff, 120 BPM, bright and playful",
    "response_format": "mp3"
  }'
202 Accepted
{
  "job_id": "0192c48e-7c1b-7f2a-9c3d-1b2a3c4d5e6f",
  "status": "processing",
  "model": "lyria-3-clip-preview",
  "result_url": null,
  "cost": null,
  "error": null,
  "assets": [],
  "lyrics": [],
  "structure": [],
  "capture_status": null
}

パラメータ#

パラメータ型必須説明
modelstring任意lyria-3-clip-preview（デフォルト）または lyria-3-pro-preview。それ以外のモデル ID は拒否されます。
promptstring必須音楽の説明。1〜8,000 文字。
imagesstring[] (UUID)任意参照画像の Playground アセット ID。最大 10 件、重複不可。リクエストキーの所有者 が所有するアセットのみ受け付けます — 任意の URL・base64 は不可です。
response_format"mp3" | "wav"任意デフォルトは mp3。wav は Pro モデルのみ対応し、Clip は MP3 に強制されます。
Clip は高速クリップ生成用、Pro は WAV 出力が必要な高品位ワーク用です。認識できない model 値はスキーマ検証（422）で拒否されます。

状態照会#

ジョブ状態は動画・3D と共通のライフサイクル GET /v1/jobs/{job_id} で照会します。 status は processing → succeeded | failed | canceled の順に進みます。

GET/v1/jobs/{job_id}

音楽ジョブは lyrics（モデルが生成した歌詞テキスト）と structure（セクション構造）フィールドも公開します。成功時の cost は最終精算額です。

結果ダウンロード#

GET /v1/jobs/{job_id}/result は 307 リダイレクトで短命の事前署名ダウンロード URL を返します。 URL は送信した API キーにのみ発行され、リダイレクトを追う HTTP クライアントはバイナリオーディオを受け取ります。

GET/v1/jobs/{job_id}/result
submit + poll + download (Python)
import time
import requests

base = "https://apirouter.pleum.ai/v1"
headers = {"Authorization": "Bearer plm_..."}

job = requests.post(
    f"{base}/audio/generations",
    headers=headers,
    json={
        "model": "lyria-3-clip-preview",
        "prompt": "Upbeat k-pop synth riff, 120 BPM, bright and playful",
    },
    timeout=30,
).json()

while True:
    job = requests.get(f"{base}/jobs/{job['job_id']}", headers=headers, timeout=30).json()
    if job["status"] != "processing":
        break
    time.sleep(5)

if job["status"] != "succeeded":
    raise SystemExit(job["error"])

# 307 리다이렉션을 따라가면 짧은 만료의 사전서명 다운로드 URL로 이어진다.
audio = requests.get(
    f"{base}/jobs/{job['job_id']}/result",
    headers=headers,
    allow_redirects=True,
    timeout=120,
)
with open("out.mp3", "wb") as f:
    f.write(audio.content)

print(job.get("lyrics") or [])

課金と安全装置#

送信時にクレジットをホールドし、成功時のみ精算されます（失敗・キャンセルは未課金）。 Idempotency-Key ヘッダー（英数字開始 8〜128 文字）を送ると、 ネットワーク再試行で同じ音楽が二重生成されるのを防げます。

メディア生成にサーバー側の自動リトライはありません。失敗時はパラメータを確認して再送 してください。BYOK（自分のキー）は音楽を含む非同期生成では未対応です。