v4

OpenAPI 3.1.02026-07-313621,3961.8 MB

music-generation

Compose Music With A Detailed Response

Compose a song from a prompt or a composition plan.

post/v1/music/detailed

Query parameters

output_format'auto' | 'mp3_48000_128' | 'mp3_48000_192' | 'mp3_48000_240' | 'mp3_48000_320' | 'mp3_22050_32' | 'mp3_24000_48' | 'mp3_44100_32' | 'mp3_44100_64' | 'mp3_44100_96' | 'mp3_44100_128' | 'mp3_44100_192' | 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_32000' | 'pcm_44100' | 'pcm_48000' | 'ulaw_8000' | 'alaw_8000' | 'opus_48000_32' | 'opus_48000_64' | 'opus_48000_96' | 'opus_48000_128' | 'opus_48000_192'

Output format of the generated audio. Formatted as codec_sample_rate_bitrate. Use "auto" (the default) to let the API pick the best format for the selected model: mp3_44100_128 for v1 models and mp3_48000_192 for v2 models.

Headers

xi-api-keystring 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

promptstring nullable

A simple text prompt to generate a song from. Cannot be used in conjunction with composition_plan.

generation_mode'track' | 'loop' | 'ambience' | 'video_to_music' nullable

Optional generation mode hint for prompt-based music generation. Can only be used with prompt.

lyrics_textstring nullable

The lyrics text to use for the generation.

music_length_msinteger nullable

The length of the song to generate in milliseconds. Used only in conjunction with prompt. Must be between 3000ms and 600000ms. Optional - if not provided, the model will choose a length based on the prompt.

model_id'music_v1' | 'music_v2'

The model to use for the generation.

seedinteger nullable

Random seed to initialize the music generation process. Providing the same seed with the same parameters can help achieve more consistent results, but exact reproducibility is not guaranteed and outputs may change across system updates. Cannot be used in conjunction with prompt.

force_instrumentalboolean

If true, guarantees that the generated song will be instrumental. If false, the song may or may not be instrumental depending on the prompt. Can only be used with prompt.

finetune_idstring nullable

The ID of the finetune to use for the generation

finetune_strengthnumber

How strongly the finetune influences the generation. Defaults to 1.0 (full strength). Lower values soften the influence of the finetune, leaving more room for prompt-level steering. Only meaningful when finetune_id is also provided.

use_phonetic_namesboolean

If true, proper names in the prompt will be phonetically spelled in the lyrics for better pronunciation by the music model. The original names will be restored in word timestamps.

respect_sections_durationsboolean

Controls how strictly section durations in the composition_plan are enforced. Only used with composition_plan and only applies to music_v1; for music_v2 section durations are always enforced and this is ignored. When false for music_v1, the model may adjust individual section durations for better quality and latency, while preserving the total song duration from the plan.

store_for_inpaintingboolean

Whether to store the generated song for inpainting.

with_timestampsboolean

Whether to return the timestamps of the words in the generated song.

sign_with_c2paboolean

Whether to sign the generated song with C2PA. Applicable only for mp3 files.

model_style_prefix'music' | 'sfx'

Example request

{
  "music_prompt": {
    "negative_global_styles": [
      "metal",
      "hip-hop",
      "country"
    ],
    "positive_global_styles": [
      "pop",
      "rock",
      "jazz"
    ],
    "sections": [
      {
        "duration_ms": 10000,
        "lines": [
          "Verse 1 lyrics"
        ],
        "negative_local_styles": [
          "metal",
          "hip-hop",
          "country"
        ],
        "positive_local_styles": [
          "pop",
          "rock",
          "jazz"
        ],
        "section_name": "Verse 1"
      }
    ]
  },
  "composition_plan": {
    "negative_global_styles": [
      "metal",
      "hip-hop",
      "country"
    ],
    "positive_global_styles": [
      "pop",
      "rock",
      "jazz"
    ],
    "sections": [
      {
        "duration_ms": 10000,
        "lines": [
          "Verse 1 lyrics"
        ],
        "negative_local_styles": [
          "metal",
          "hip-hop",
          "country"
        ],
        "positive_local_styles": [
          "pop",
          "rock",
          "jazz"
        ],
        "section_name": "Verse 1"
      }
    ]
  }
}

Response

Multipart/mixed response with JSON metadata and binary audio file