> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Componi musica con una risposta dettagliata

POST https://api.elevenlabs.io/v1/music/detailed
Content-Type: application/json

Componi una canzone da un prompt o da un piano di composizione.

Reference: https://elevenlabs.io/docs/api-reference/music/compose-detailed

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Query parameters

- `output_format` (enum, optional, default: auto) — Formato di output dell'audio generato. Formattato come codec_sample_rate_bitrate. Usa "auto", il valore predefinito, per lasciare che l'API scelga il formato migliore per il modello selezionato: mp3_44100_128 per i modelli v1 e mp3_48000_192 per i modelli v2.
  - Allowed values: `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`

### Body (application/json)

This endpoint expects a Body_Compose_Music_with_a_detailed_response_v1_music_detailed_post.

- `prompt` (string, optional, nullable) — Un semplice prompt di testo da cui generare una canzone. Non può essere usato insieme a `composition_plan`.
- `composition_plan` (BodyComposeMusicWithADetailedResponseV1MusicDetailedPostCompositionPlan, optional, nullable) — Un piano di composizione dettagliato per guidare la generazione musicale. Non può essere usato insieme a `prompt`.
- `music_length_ms` (integer, optional, nullable) — La durata del brano da generare in millisecondi. Utilizzata solo insieme a `prompt`. Deve essere compresa tra 3000 ms e 600000 ms. Facoltativo: se non specificata, il modello sceglierà una durata in base al prompt.
- `model_id` (enum, optional, default: music_v1) — Il modello da usare per la generazione.
  - Allowed values: `music_v1`, `music_v2`, `music_v2_5`
- `seed` (integer, optional, nullable) — Seed casuale per inizializzare il processo di generazione musicale. Fornire lo stesso seed con gli stessi parametri può aiutare a ottenere risultati più coerenti, ma la riproducibilità esatta non è garantita e gli output possono cambiare con gli aggiornamenti del sistema. Non può essere utilizzato insieme a prompt.
- `force_instrumental` (boolean, optional, default: false) — Se true, garantisce che la canzone generata sia strumentale. Se false, la canzone potrebbe essere o non essere strumentale in base al `prompt`. Può essere usato solo con `prompt`.
- `finetune_id` (string, optional, nullable) — L'ID del Finetune da usare per la generazione
- `respect_sections_durations` (boolean, optional, default: true) — Controlla quanto rigorosamente vengono rispettate le durate delle sezioni nel `composition_plan`. Viene usato solo con `composition_plan` e si applica solo a `music_v1`; per `music_v2` e `music_v2_5` le durate delle sezioni vengono sempre rispettate e questo parametro viene ignorato. Se è false per `music_v1`, il modello può modificare le durate delle singole sezioni per migliorare qualità e latenza, preservando la durata totale del brano indicata nel piano.
- `store_for_inpainting` (boolean, optional, default: false) — Indica se archiviare la canzone generata per l'inpainting.
- `with_timestamps` (boolean, optional, default: false) — Indica se restituire i timestamp delle parole nella canzone generata.
- `with_waveform_visual` (boolean, optional, default: false) — Indica se restituire la forma d'onda visiva della canzone generata.
- `sign_with_c2pa` (boolean, optional, default: false) — Indica se firmare la canzone generata con C2PA. Si applica solo ai file mp3.

## Response

### 200

Risposta multipart/mixed con metadati JSON e file audio binario

## Errors

### 422 Unprocessable Entity Error

Errore di convalida

- `detail` (list of ValidationError, optional)

## Types

### BodyComposeMusicWithADetailedResponseV1MusicDetailedPostCompositionPlan

Un piano di composizione dettagliato per guidare la generazione musicale. Non può essere usato insieme a `prompt`.

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### MusicPrompt

Piano di composizione per il modello `music_v1`. L'uso di questo campo con qualsiasi altro modello genererà un errore.

- `positive_global_styles` (list of string, required) — Gli stili e le indicazioni musicali che devono essere presenti nell'intero brano. Per risultati migliori, usa l'inglese.
- `negative_global_styles` (list of string, required) — Gli stili e le indicazioni musicali che non devono essere presenti nell'intero brano. Per risultati migliori, usa l'inglese.
- `sections` (list of SongSection, required) — Le sezioni del brano.

### CompositionPlan

Piano di composizione per i modelli `music_v2` e `music_v2_5`. L'uso di questo campo con qualsiasi altro modello genererà un errore.

- `chunks` (list of CompositionPlanChunksItems, required) — I blocchi che compongono la generazione.

### ValidationErrorLocItems

### SongSection

- `section_name` (string, required) — Il nome della sezione. Deve contenere da 1 a 100 caratteri.
- `positive_local_styles` (list of string, required) — Gli stili e le indicazioni musicali che devono essere presenti in questa sezione. Per risultati migliori, usa l'inglese.
- `negative_local_styles` (list of string, required) — Gli stili e le indicazioni musicali che non devono essere presenti in questa sezione. Per risultati migliori, usa l'inglese.
- `duration_ms` (integer, required) — La durata della sezione in millisecondi. Deve essere compresa tra 3000 ms e 120000 ms.
- `lines` (list of string, required) — Il testo della sezione. Massimo 30 righe per sezione e 200 caratteri per riga.
- `source_from` (SectionSource, optional, nullable) — Origine facoltativa da cui estrarre la sezione. Usata per l'inpainting.

### CompositionPlanChunksItems

### SectionSource

- `song_id` (string, required) — L'ID del brano da cui estrarre la sezione. Puoi trovare l'ID del brano negli header della risposta quando generi un brano.
- `range` (TimeRange, required) — L'intervallo da estrarre dal brano sorgente.
- `negative_ranges` (list of TimeRange, optional) — Gli intervalli da escludere da 'range'.

### GenerationChunk-Input

- `text` (string, required) — La configurazione del testo da generare per questo segmento. Può contenere un nome di sezione facoltativo tra parentesi quadre all'inizio, ad esempio \[Verse 1], righe di testo e indicazioni inline tra parentesi graffe, ad esempio \{scratching}. I nomi delle sezioni devono contenere da 1 a 100 caratteri. Sono consentite al massimo 30 righe, ciascuna di massimo 200 caratteri.
- `duration_ms` (integer, required) — La durata del chunk in millisecondi. Deve essere compresa tra 3000 ms e 120000 ms.
- `positive_styles` (list of string, required) — Gli stili e le indicazioni musicali che devono essere presenti in questo segmento. Per risultati migliori, usa l'inglese. Gli stili del primo segmento sono i più importanti perché definiscono il tono e il genere generali. Gli stili dei segmenti successivi possono aggiungere sfumature, progressione, enfasi o modificare la direzione del brano. Cerca di inserire almeno 6-7 stili nei primi segmenti, finché non è definita una direzione. Stili generici come 'great production quality' sono buone opzioni predefinite da aggiungere all'elenco.
- `negative_styles` (list of string, optional) — Gli stili e le indicazioni musicali che non devono essere presenti in questo segmento. Per risultati migliori, usa l'inglese. Lasciare il campo vuoto è una buona impostazione predefinita; usalo se vuoi evitare esplicitamente uno stile o una direzione specifici.
- `context_adherence` (enum, optional, default: high) — Quanto il modello aderisce al contesto dei chunk circostanti. Un'aderenza bassa significa che il modello può discostarsi dal contesto ed essere più creativo. Un'aderenza alta significa che il modello sarà più coerente con il contesto.
  - Allowed values: `low`, `medium`, `high`
- `conditioning_ref` (AudioRefChunk, optional, nullable) — Il riferimento audio su cui condizionare la generazione. Il primo blocco è il più importante, poiché influenzerà la generazione di tutti i blocchi successivi. Pertanto, se vuoi applicare il condizionamento all'intera canzone, avvialo dal primo blocco.
- `condition_strength` (enum, optional, nullable) — Quanto il modello aderisce al riferimento di condizionamento. Un'intensità bassa rende il modello più creativo e meno aderente al riferimento. Un'intensità alta rende il modello più coerente con il riferimento.
  - Allowed values: `low`, `medium`, `high`, `xhigh`

### AudioRefChunk

- `song_id` (string, required) — L'ID del brano da cui estrarre il chunk. Puoi trovare l'ID del brano negli header della risposta quando generi un brano.
- `range` (TimeRange, required) — L'intervallo di tempo da estrarre dal brano.

### TimeRange

- `start_ms` (integer, required)
- `end_ms` (integer, required)

## Examples

**Request**

```json
{
  "prompt": "A prompt for music generation",
  "music_length_ms": 10000
}
```

**Response**

```json
{
  "audio": "[binary audio data]",
  "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"
      }
    ]
  },
  "song_metadata": {
    "description": "Descrizione della mia canzone",
    "genres": [
      "pop",
      "rock",
      "jazz"
    ],
    "is_explicit": false,
    "languages": [
      "en",
      "fr"
    ],
    "title": "My Song"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/music/detailed"

payload = {
    "prompt": "A prompt for music generation",
    "music_length_ms": 10000
}
headers = {
    "xi-api-key": "xi-api-key",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/music/detailed';
const options = {
  method: 'POST',
  headers: {'xi-api-key': 'xi-api-key', 'Content-Type': 'application/json'},
  body: '{"prompt":"A prompt for music generation","music_length_ms":10000}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/music/detailed"

	payload := strings.NewReader("{\n  \"prompt\": \"A prompt for music generation\",\n  \"music_length_ms\": 10000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("xi-api-key", "xi-api-key")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/music/detailed")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["xi-api-key"] = 'xi-api-key'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"A prompt for music generation\",\n  \"music_length_ms\": 10000\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/music/detailed")
  .header("xi-api-key", "xi-api-key")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"A prompt for music generation\",\n  \"music_length_ms\": 10000\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/music/detailed', [
  'body' => '{
  "prompt": "A prompt for music generation",
  "music_length_ms": 10000
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'xi-api-key' => 'xi-api-key',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/music/detailed");
var request = new RestRequest(Method.POST);
request.AddHeader("xi-api-key", "xi-api-key");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"prompt\": \"A prompt for music generation\",\n  \"music_length_ms\": 10000\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "xi-api-key": "xi-api-key",
  "Content-Type": "application/json"
]
let parameters = [
  "prompt": "A prompt for music generation",
  "music_length_ms": 10000
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/music/detailed")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```