Music generation

An async job API that generates audio clips from prompts with Lyria 3.

Music generation runs as an async job, unlike text and images. Submission returns 202 Accepted immediately; you poll the job and download the audio via a presigned URL on success. For speech synthesis (TTS) and transcription (STT), see /v1/audio/speech and /v1/audio/transcriptions.

Submit#

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
}

Parameters#

Parameter	Type	Required	Description
model	string	Optional	`lyria-3-clip-preview` (default) or `lyria-3-pro-preview`. Any other model ID is rejected.
prompt	string	Required	Music description. 1–8,000 characters.
images	string[] (UUID)	Optional	Playground asset IDs of reference images. Up to 10, no duplicates. Only assets owned by the requesting key are accepted — arbitrary URLs and base64 are not.
response_format	"mp3" \| "wav"	Optional	Defaults to `mp3`. `wav` requires the Pro model; Clip is forced to MP3.

Clip targets fast clip generation; Pro targets higher-fidelity work needing WAV output. Unrecognized model values fail schema validation (422).

Polling#

Poll the job through the shared lifecycle endpoint GET /v1/jobs/{job_id}, as with video and 3D. status progresses as processing → succeeded | failed | canceled.

GET/v1/jobs/{job_id}

Music jobs additionally expose lyrics (the model's generated lyric text) and structure (section structure). cost holds the final settled amount on success.

Downloading the result#

GET /v1/jobs/{job_id}/result responds with a 307 redirect to a short-lived presigned download URL. The URL is issued only to the submitting API key; an HTTP client that follows the redirect receives the binary audio.

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 [])

Billing and safeguards#

Credits are held at submission and settled only on success (failures and cancellations are not charged). Send an Idempotency-Key header (alphanumeric start, 8–128 chars) to prevent network retries from double-generating the same music.

Media generation has no server-side auto-retry. On failure, check your parameters and resubmit. BYOK (bring your own key) is not supported for async generation including music.