Music Generation
Generate music from text prompts and poll for the finished track.
Music generation is asynchronous: submit a job, receive a record with a status, then poll until it
is completed. Discover music models with the Models API
(GET /v1/models?type=music_generation).
Generate music
POST /v1/music/generationsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Music model id. |
prompt | string | Yes | Description of the music to generate. |
duration | integer | No | Length in seconds (5–300). Default 30. |
genre | string | No | Genre hint, e.g. pop, rock, classical, electronic. |
tempo | string | No | Tempo hint, e.g. slow, medium, fast. |
mood | string | No | Mood hint, e.g. happy, calm, energetic. |
instruments | string[] | No | Instruments to include. |
with_vocals | boolean | No | Generate vocals. Default false. |
lyrics | string | No | Lyrics to sing when with_vocals is true. |
Which hints a model honors (genre, tempo, vocals, lyrics) is model-specific — check
GET /v1/models/{model_id}.
Response
The endpoint returns a job record. While the track renders, status is pending or processing:
{
"id": "music_abc123",
"status": "processing",
"created_at": 1709251200,
"model": "model-id",
"prompt": "A calm piano piece with soft strings, suitable for meditation",
"duration": 60,
"format": "mp3"
}When finished, status is completed and the audio is available via url (with optional
waveform_url, sample_rate, and a structured audio object). On failure, status is failed and
error describes why.
Poll a track
GET /v1/music/{id}Returns the current job record (same shape as the create response). Poll until status is completed
or failed.
Delete a track
DELETE /v1/music/{id}Removes the job and its generated audio.
Example
import os, time, httpx
BASE = "https://api.yuhuanstudio.com/v1"
headers = {"Authorization": f"Bearer {os.environ['YUNXIN_API_KEY']}"}
# Submit the generation job
job = httpx.post(
f"{BASE}/music/generations",
headers=headers,
json={
"model": "model-id",
"prompt": "An upbeat electronic track with synths and a driving beat",
"duration": 60,
},
).json()
music_id = job["id"]
# Poll until the job finishes
while True:
status = httpx.get(f"{BASE}/music/{music_id}", headers=headers).json()
if status["status"] == "completed":
print(f"Music ready: {status['url']}")
break
if status["status"] == "failed":
print(f"Generation failed: {status.get('error')}")
break
time.sleep(5)Music models are provider-specific (e.g. MiniMax) and may not be enabled on every account. List what's
available with GET /v1/models?type=music_generation.
How is this guide?