# ElevenLabs Music

This document describes how to call the ElevenLabs `music-v1` music generation model, which supports four endpoints: standard generation, streaming generation, detailed mode, and composition plan generation.

> **Official Documentation Reference**:
> - [Compose music](https://elevenlabs.io/docs/api-reference/music/compose)
> - [Stream music](https://elevenlabs.io/docs/api-reference/music/stream)
> - [Compose music with details](https://elevenlabs.io/docs/api-reference/music/compose-detailed)
> - [Create composition plan](https://elevenlabs.io/docs/api-reference/music/create-composition-plan)

---

## Music Generation (Synchronous) [Official Docs](https://elevenlabs.io/docs/api-reference/music/compose)

### Endpoint

`POST https://api-us-ca.umodelverse.ai/v1/audio/music/generate`

### Input

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| model | string | Yes | Model name, fixed value: `music-v1` |
| input | string | One of two | Music description prompt, up to 4100 characters. Cannot be used together with `composition_plan` |
| composition_plan | object | One of two | Structured composition plan for precise control over music generation. Cannot be used together with `input` |
| composition_plan.positive_global_styles | array | No | Global positive style tags |
| composition_plan.negative_global_styles | array | No | Global negative style tags (styles to avoid) |
| composition_plan.sections | array(object) | No | List of sections |
| composition_plan.sections.section_name | string | No | Section name |
| composition_plan.sections.positive_local_styles | array(string) | No | Section positive styles |
| composition_plan.sections.negative_local_styles | array(string) | No | Section negative styles |
| composition_plan.sections.duration_ms | integer | No | Section duration (milliseconds) |
| composition_plan.sections.lines | array(string) | No | Lyric lines |
| music_length_ms | integer | Yes | Music duration (milliseconds), range: 1–600000 |
| seed | integer | No | Random seed, range: 0–2147483647, for more consistent results. Only usable with `composition_plan`; cannot be used together with `input` |
| force_instrumental | boolean | No | Whether to force instrumental-only output. Default is `false`. Only usable with `input` |
| output_format | string | No | Output audio format, e.g., `mp3_22050_32` (MP3, 22.05 kHz, 32 kbps) |

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/audio/music/generate' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "music-v1",
  "input": "A happy piano melody with soft jazz undertones",
  "music_length_ms": 30000,
  "output_format": "mp3_22050_32"
}' \
--output music.mp3
```

### Output

Returns a binary audio stream directly. The format is determined by `output_format`, defaulting to MP3.

### Response Headers

| Parameter | Type | Description |
| :--- | :--- | :--- |
| song-id | string | Unique identifier of the generated song |

---

## Music Generation (Streaming) [Official Docs](https://elevenlabs.io/docs/api-reference/music/stream)

### Endpoint

`POST https://api-us-ca.umodelverse.ai/v1/audio/music/stream`

The streaming endpoint accepts the same request parameters as the standard generation endpoint. The difference is that the response returns audio data as a stream, suitable for use cases that require playback while generating.

### Input

Same parameters as [Music Generation (Synchronous)](#music-generation-synchronous).

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/audio/music/stream' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "music-v1",
  "input": "A calm guitar piece with nature sounds",
  "music_length_ms": 30000,
  "output_format": "mp3_22050_32"
}' \
--output music_stream.mp3
```

### Output

Returns binary audio data as a stream.

---

## Music Generation (Detailed Mode) [Official Docs](https://elevenlabs.io/docs/api-reference/music/compose-detailed)

### Endpoint

`POST https://api-us-ca.umodelverse.ai/v1/audio/music/detailed`

In addition to the audio, the detailed mode endpoint also returns the composition plan and song metadata generated by the model.

### Input

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| model | string | Yes | Model name, fixed value: `music-v1` |
| input | string | One of two | Music description prompt, up to 4100 characters. Cannot be used together with `composition_plan` |
| composition_plan | object | One of two | Structured composition plan. Cannot be used together with `input` |
| music_length_ms | integer | Yes | Music duration (milliseconds), range: 1–600000. Only usable with `input` |
| seed | integer | No | Random seed, range: 0–2147483647. Only usable with `composition_plan`; cannot be used together with `input` |
| force_instrumental | boolean | No | Whether to force instrumental-only output. Default is `false`. Only usable with `input` |
| respect_sections_durations | boolean | No | Whether to strictly follow section durations. Default is `true`. Only usable with `composition_plan` |
| with_timestamps | boolean | No | Whether to return lyric timestamps. Default is `false` |
| output_format | string | No | Output audio format |

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/audio/music/detailed' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "music-v1",
  "input": "An upbeat jazz tune",
  "music_length_ms": 10000
}' \
--output music_detailed.mp3
```

### Output

The response is in `multipart/mixed` format and contains two parts:

1. **JSON metadata** — contains the composition plan and song metadata
2. **Binary audio data** — the generated audio file

### Metadata Structure

| Parameter | Type | Description |
| :--- | :--- | :--- |
| composition_plan | object | Composition plan generated by the model |
| composition_plan.positive_global_styles | array | Global positive style tags |
| composition_plan.negative_global_styles | array | Global negative style tags |
| composition_plan.sections | array(object) | List of sections |
| composition_plan.sections.section_name | string | Section name |
| composition_plan.sections.positive_local_styles | array(string) | Section positive styles |
| composition_plan.sections.negative_local_styles | array(string) | Section negative styles |
| composition_plan.sections.duration_ms | integer | Section duration (milliseconds) |
| composition_plan.sections.lines | array(string) | Lyric lines |
| song_metadata | object | Song metadata |
| song_metadata.title | string | Song title |
| song_metadata.description | string | Song description |
| song_metadata.genres | array | Music genres |
| song_metadata.languages | array | Languages |
| song_metadata.is_explicit | boolean | Whether the content is explicit |

### Metadata Response Example

```json
{
  "composition_plan": {
    "positive_global_styles": ["jazz", "upbeat"],
    "negative_global_styles": ["heavy metal", "aggressive"],
    "sections": [
      {
        "section_name": "Intro",
        "positive_local_styles": ["piano", "light percussion"],
        "negative_local_styles": ["vocals", "distortion"],
        "duration_ms": 3000,
        "lines": []
      },
      {
        "section_name": "Verse",
        "positive_local_styles": ["saxophone", "swing rhythm"],
        "negative_local_styles": ["harsh drums"],
        "duration_ms": 7000,
        "lines": ["Swinging through the night..."]
      }
    ]
  },
  "song_metadata": {
    "title": "Jazz Evening",
    "description": "An upbeat jazz composition",
    "genres": ["jazz"],
    "languages": ["en"],
    "is_explicit": false
  }
}
```

---

## Composition Plan Generation [Official Docs](https://elevenlabs.io/docs/api-reference/music/create-composition-plan)

### Endpoint

`POST https://api-us-ca.umodelverse.ai/v1/audio/music/plan`

Generates a structured composition plan from a text description, which can be used for subsequent music generation. **This endpoint does not consume any credits.**

### Input

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| model | string | Yes | Model name, fixed value: `music-v1` |
| prompt | string | Yes | Composition description prompt, up to 4100 characters |
| music_length_ms | integer | No | Total duration (milliseconds), range: 3000–600000. If omitted, the model decides automatically |
| source_composition_plan | object | No | Generate a new composition plan based on an existing one |

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/audio/music/plan' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "music-v1",
  "prompt": "A soft lullaby with gentle piano and female vocals",
  "music_length_ms": 30000
}'
```

### Output

| Parameter | Type | Description |
| :--- | :--- | :--- |
| positive_global_styles | array | Global positive style tags (English recommended) |
| negative_global_styles | array | Global negative style tags (English recommended) |
| sections | array(object) | List of sections |
| sections.section_name | string | Section name |
| sections.positive_local_styles | array(string) | Section positive styles |
| sections.negative_local_styles | array(string) | Section negative styles |
| sections.duration_ms | integer | Section duration (milliseconds) |
| sections.lines | array(string) | Lyric lines |

### Response Example

```json
{
  "positive_global_styles": ["lullaby", "soft", "gentle", "calming", "acoustic"],
  "negative_global_styles": ["loud", "heavy drums", "fast tempo", "aggressive"],
  "sections": [
    {
      "section_name": "Verse 1",
      "positive_local_styles": ["soft female vocal", "gentle acoustic guitar", "slow tempo"],
      "negative_local_styles": ["percussion", "bass guitar"],
      "duration_ms": 15000,
      "lines": [
        "Close your eyes and drift away,",
        "Safe and sound until the day."
      ]
    },
    {
      "section_name": "Verse 2",
      "positive_local_styles": ["soft female vocal", "hushed delivery", "dreamy atmosphere"],
      "negative_local_styles": ["strong vocals", "drums"],
      "duration_ms": 15000,
      "lines": [
        "Stars above are shining bright,",
        "Sleep now, darling, sleep so deep."
      ]
    }
  ]
}
```

> **Tip**: The generated `composition_plan` can be passed directly to the `composition_plan` parameter of the music generation endpoints to achieve precise, plan-based music generation.