# Music Generation (/docs/music)


Endpoint [#endpoint]

```
POST /v1/music/generations
```

Request [#request]

```json
{
  "model": "model-id",
  "prompt": "An upbeat electronic track with synths and a driving beat",
  "duration": 30,
  "format": "mp3"
}
```

Parameters [#parameters]

| Parameter  | Type    | Required | Description                      |
| ---------- | ------- | -------- | -------------------------------- |
| `model`    | string  | Yes      | Music model ID                   |
| `prompt`   | string  | Yes      | Description of the desired music |
| `duration` | integer | No       | Duration in seconds              |
| `format`   | string  | No       | Output format (`mp3`, `wav`)     |

Response [#response]

Music generation follows an asynchronous pattern similar to video generation:

```json
{
  "id": "music_abc123",
  "status": "processing",
  "created_at": 1709251200
}
```

Check Status [#check-status]

```
GET /v1/music/generations/{id}
```

Available Models [#available-models]

<Callout type="info">
  For a list of available music models and their capabilities, please use the [Models API](/docs/models-api) with `GET /v1/models?type=music_generation`.
</Callout>

Example [#example]

```python
import httpx
import time

response = httpx.post(
    "https://api.yuhuanstudio.com/v1/music/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "model-id",
        "prompt": "A calm piano piece with soft strings, suitable for meditation",
        "duration": 60
    }
)

task = response.json()
task_id = task["id"]

# Poll for completion
while True:
    status = httpx.get(
        f"https://api.yuhuanstudio.com/v1/music/generations/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    ).json()

    if status["status"] == "completed":
        print(f"Music ready: {status['audio_url']}")
        break
    elif status["status"] == "failed":
        print(f"Generation failed: {status.get('error')}")
        break

    time.sleep(5)
```

<Callout type="info">
  Music generation availability depends on your subscribed providers. Check the Dashboard for available music models.
</Callout>