---
title: "Generate Composition Plan"
method: POST
path: "/v1/music/plan"
tags: ["music-generation"]
---

# Generate Composition Plan

`POST /v1/music/plan`

Generate a composition plan from a prompt.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- BodyGenerateCompositionPlanV1MusicPlanPost
  - `prompt` string, required — A simple text prompt to compose a plan from.
  - `music_length_ms` integer, nullable — The length of the composition plan to generate in milliseconds. Must be between 3000ms and 600000ms. Optional - if not provided, the model will choose a length based on the prompt.
  - `source_composition_plan` union — An optional composition plan to use as a source for the new composition plan.
    - MusicPrompt — Composition plan for the `music_v1` model. Using this field with any other model will result in an error.
      - `positive_global_styles` string[], required — The styles and musical directions that should be present in the entire song. Use English language for best result.
      - `negative_global_styles` string[], required — The styles and musical directions that should not be present in the entire song. Use English language for best result.
      - `sections` SongSection[], required — The sections of the song.
        - `section_name` string, required — The name of the section. Must be between 1 and 100 characters.
        - `positive_local_styles` string[], required — The styles and musical directions that should be present in this section. Use English language for best result.
        - `negative_local_styles` string[], required — The styles and musical directions that should not be present in this section. Use English language for best result.
        - `duration_ms` integer, required — The duration of the section in milliseconds. Must be between 3000ms and 120000ms.
        - `lines` string[], required — The lyrics of the section. Max 30 lines per section and max 200 characters per line.
        - `source_from` SectionSource
          - `song_id` string, required — The ID of the song to source the section from. You can find the song ID in the response headers when you generate a song.
          - `range` TimeRange, required
            - `start_ms` integer, required
            - `end_ms` integer, required
          - `negative_ranges` TimeRange[] — The ranges to exclude from the 'range'.
            - `start_ms` integer, required
            - `end_ms` integer, required
    - CompositionPlan — Composition plan for the `music_v2` model. Using this field with any other model will result in an error.
      - `chunks` union[], required — The chunks that make up the generation.
        - union
          - GenerationChunkInput
            - `text` string, required — The text config to be generated for this chunk. Can contain section name in square brackets, e.g. [Verse 1], lyrics lines, and inline directions in curly braces, e.g. {scratching}.
            - `duration_ms` integer, required — The duration of the chunk in milliseconds. Must be between 3000ms and 120000ms.
            - `positive_styles` string[], required — The styles and musical directions that should be present in this chunk. Use English language for best results. The styles for the first chunk are the most important as they set the overall tone and genre. Styles for subsequent chunks can be used to add nuance, progression, emphasis, or change the direction of the song. Aim to have at least 6-7 styles in early chunks until the direction is established. Generic styles like 'great production quality' are good default styles to append to the list.
            - `negative_styles` string[] — The styles and musical directions that should not be present in this chunk. Use English language for best results. Leaving empty is a good default, only use this field if you want to explicitly avoid a particular style or direction.
            - `context_adherence` 'low' | 'medium' | 'high' — How much the model adheres to the context of its surrounding chunks. Low adherence means the model can deviate from the context and be more creative. High adherence means the model will be more consistent with the context.
            - `conditioning_ref` AudioRefChunk
              - …
            - `condition_strength` 'low' | 'medium' | 'high' | 'xhigh', nullable — How strongly the model adheres to the conditioning reference. Low strength means the model will be more creative and deviate from the reference. High strength means the model will be more consistent with the reference.
          - AudioRefChunk
            - `song_id` string, required — The ID of the song to source the chunk from. You can find the song ID in the response headers when you generate a song.
            - `range` TimeRange, required
              - …
  - `model_id` 'music_v1' | 'music_v2' — The model to use for the generation.

## Response `200`

Successful Response

- union
  - MusicPrompt — Composition plan for the `music_v1` model. Using this field with any other model will result in an error.
    - `positive_global_styles` string[], required — The styles and musical directions that should be present in the entire song. Use English language for best result.
    - `negative_global_styles` string[], required — The styles and musical directions that should not be present in the entire song. Use English language for best result.
    - `sections` SongSection[], required — The sections of the song.
      - `section_name` string, required — The name of the section. Must be between 1 and 100 characters.
      - `positive_local_styles` string[], required — The styles and musical directions that should be present in this section. Use English language for best result.
      - `negative_local_styles` string[], required — The styles and musical directions that should not be present in this section. Use English language for best result.
      - `duration_ms` integer, required — The duration of the section in milliseconds. Must be between 3000ms and 120000ms.
      - `lines` string[], required — The lyrics of the section. Max 30 lines per section and max 200 characters per line.
      - `source_from` SectionSource
        - `song_id` string, required — The ID of the song to source the section from. You can find the song ID in the response headers when you generate a song.
        - `range` TimeRange, required
          - `start_ms` integer, required
          - `end_ms` integer, required
        - `negative_ranges` TimeRange[] — The ranges to exclude from the 'range'.
          - `start_ms` integer, required
          - `end_ms` integer, required
  - CompositionPlan — Composition plan for the `music_v2` model. Using this field with any other model will result in an error.
    - `chunks` union[], required — The chunks that make up the generation.
      - union
        - GenerationChunkInput
          - `text` string, required — The text config to be generated for this chunk. Can contain section name in square brackets, e.g. [Verse 1], lyrics lines, and inline directions in curly braces, e.g. {scratching}.
          - `duration_ms` integer, required — The duration of the chunk in milliseconds. Must be between 3000ms and 120000ms.
          - `positive_styles` string[], required — The styles and musical directions that should be present in this chunk. Use English language for best results. The styles for the first chunk are the most important as they set the overall tone and genre. Styles for subsequent chunks can be used to add nuance, progression, emphasis, or change the direction of the song. Aim to have at least 6-7 styles in early chunks until the direction is established. Generic styles like 'great production quality' are good default styles to append to the list.
          - `negative_styles` string[] — The styles and musical directions that should not be present in this chunk. Use English language for best results. Leaving empty is a good default, only use this field if you want to explicitly avoid a particular style or direction.
          - `context_adherence` 'low' | 'medium' | 'high' — How much the model adheres to the context of its surrounding chunks. Low adherence means the model can deviate from the context and be more creative. High adherence means the model will be more consistent with the context.
          - `conditioning_ref` AudioRefChunk
            - `song_id` string, required — The ID of the song to source the chunk from. You can find the song ID in the response headers when you generate a song.
            - `range` TimeRange, required
              - …
          - `condition_strength` 'low' | 'medium' | 'high' | 'xhigh', nullable — How strongly the model adheres to the conditioning reference. Low strength means the model will be more creative and deviate from the reference. High strength means the model will be more consistent with the reference.
        - AudioRefChunk
          - `song_id` string, required — The ID of the song to source the chunk from. You can find the song ID in the response headers when you generate a song.
          - `range` TimeRange, required
            - `start_ms` integer, required
            - `end_ms` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/revisions/6c2d6eb4a7e6/schema)