> 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.

# Componer música con una respuesta detallada

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

Compone una canción a partir de un prompt o un plan de composición.

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 de salida del audio generado. Tiene el formato codec_sample_rate_bitrate. Usa "auto" (el valor predeterminado) para que la API elija el mejor formato para el modelo seleccionado: mp3_44100_128 para modelos v1 y mp3_48000_192 para modelos 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`
- `enable_logging` (boolean, optional, default: true) — Cuando enable_logging se establece en false, se usará el modo de retención cero para la solicitud. El modo de retención cero solo puede utilizarse por clientes Enterprise.

### Body (application/json)

This endpoint expects a Body_Compose_Music_with_a_detailed_response_v1_music_detailed_post.

- `prompt` (string, optional, nullable) — Un prompt de texto sencillo a partir del que generar una canción. No puede utilizarse junto con `composition_plan`.
- `composition_plan` (BodyComposeMusicWithADetailedResponseV1MusicDetailedPostCompositionPlan, optional, nullable) — Un plan de composición detallado para guiar la generación de música. No puede utilizarse junto con `prompt`.
- `music_length_ms` (integer, optional, nullable) — La duración de la canción que se generará, en milisegundos. Solo se usa junto con `prompt`. Debe estar entre 3000 ms y 600000 ms. Opcional: si no se proporciona, el modelo elegirá una duración según el prompt.
- `model_id` (enum, optional, default: music_v1) — El modelo que se debe usar para la generación.
  - Allowed values: `music_v1`, `music_v2`, `music_v2_5`
- `seed` (integer, optional, nullable) — Semilla aleatoria para inicializar el proceso de generación de música. Proporcionar la misma semilla con los mismos parámetros puede ayudar a obtener resultados más coherentes, pero no se garantiza una reproducibilidad exacta y los resultados pueden cambiar con las actualizaciones del sistema. No se puede usar junto con prompt.
- `force_instrumental` (boolean, optional, default: false) — Si es true, garantiza que la canción generada será instrumental. Si es false, la canción puede ser instrumental o no, según el `prompt`. Solo se puede usar con `prompt`.
- `finetune_id` (string, optional, nullable) — El ID del finetune que se usará para la generación
- `respect_sections_durations` (boolean, optional, default: true) — Controla con qué rigor se respetan las duraciones de las secciones en `composition_plan`. Solo se usa con `composition_plan` y solo se aplica a `music_v1`; en `music_v2` y `music_v2_5`, las duraciones de las secciones siempre se respetan y este parámetro se ignora. Cuando es false para `music_v1`, el modelo puede ajustar las duraciones de cada sección para mejorar la calidad y la latencia, manteniendo la duración total de la canción indicada en el plan.
- `store_for_inpainting` (boolean, optional, default: false) — Si se almacena la canción generada para inpainting.
- `with_timestamps` (boolean, optional, default: false) — Si se devuelven las marcas de tiempo de las palabras de la canción generada.
- `with_waveform_visual` (boolean, optional, default: false) — Si se devuelve la forma de onda visual de la canción generada.
- `sign_with_c2pa` (boolean, optional, default: false) — Si se firma la canción generada con C2PA. Solo aplicable a archivos mp3.

## Response

### 200

Respuesta multipart/mixed con metadatos JSON y archivo de audio binario

## Errors

### 422 Unprocessable Entity Error

Error de validación

- `detail` (list of ValidationError, optional)

## Types

### BodyComposeMusicWithADetailedResponseV1MusicDetailedPostCompositionPlan

Un plan de composición detallado para guiar la generación de música. No puede utilizarse junto con `prompt`.

### ValidationError

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

### MusicPrompt

Plan de composición para el modelo `music_v1`. Usar este campo con cualquier otro modelo producirá un error.

- `positive_global_styles` (list of string, required) — Los estilos y las indicaciones musicales que deben estar presentes en toda la canción. Usa el inglés para obtener mejores resultados.
- `negative_global_styles` (list of string, required) — Los estilos y las indicaciones musicales que no deben estar presentes en toda la canción. Usa el inglés para obtener mejores resultados.
- `sections` (list of SongSection, required) — Las secciones de la canción.

### CompositionPlan

Plan de composición para los modelos `music_v2` y `music_v2_5`. Usar este campo con cualquier otro modelo producirá un error.

- `chunks` (list of CompositionPlanChunksItems, required) — Los fragmentos que componen la generación.

### ValidationErrorLocItems

### SongSection

- `section_name` (string, required) — El nombre de la sección. Debe tener entre 1 y 100 caracteres.
- `positive_local_styles` (list of string, required) — Los estilos y las indicaciones musicales que deben estar presentes en esta sección. Usa el inglés para obtener mejores resultados.
- `negative_local_styles` (list of string, required) — Los estilos y las indicaciones musicales que no deben estar presentes en esta sección. Usa el inglés para obtener mejores resultados.
- `duration_ms` (integer, required) — La duración de la sección en milisegundos. Debe estar entre 3000 ms y 120000 ms.
- `lines` (list of string, required) — La letra de la sección. Máximo de 30 líneas por sección y 200 caracteres por línea.
- `source_from` (SectionSource, optional, nullable) — Fuente opcional de la que extraer la sección. Se utiliza para el inpainting.

### CompositionPlanChunksItems

### SectionSource

- `song_id` (string, required) — El ID de la canción de la que se obtendrá la sección. Puedes encontrar el ID de la canción en las cabeceras de respuesta al generar una canción.
- `range` (TimeRange, required) — El intervalo que se debe extraer de la canción de origen.
- `negative_ranges` (list of TimeRange, optional) — Los intervalos que se deben excluir del «range».

### GenerationChunk-Input

- `text` (string, required) — La configuración de texto que se generará para este fragmento. Puede contener un nombre de sección opcional entre corchetes al principio, por ejemplo, \[Verse 1], líneas de letra e indicaciones en línea entre llaves, por ejemplo, \{scratching}. Los nombres de sección deben tener entre 1 y 100 caracteres. Se permiten como máximo 30 líneas, de hasta 200 caracteres cada una.
- `duration_ms` (integer, required) — La duración del fragmento en milisegundos. Debe estar entre 3000 ms y 120000 ms.
- `positive_styles` (list of string, required) — Los estilos y las indicaciones musicales que deben estar presentes en este fragmento. Usa el inglés para obtener mejores resultados. Los estilos del primer fragmento son los más importantes, ya que definen el tono y el género generales. Los estilos de los fragmentos posteriores pueden usarse para añadir matices, progresión o énfasis, o para cambiar la dirección de la canción. Intenta incluir al menos 6-7 estilos en los primeros fragmentos hasta que se establezca la dirección. Los estilos genéricos como 'great production quality' son buenos estilos predeterminados para añadir a la lista.
- `negative_styles` (list of string, optional) — Los estilos y las indicaciones musicales que no deben estar presentes en este fragmento. Usa el inglés para obtener mejores resultados. Dejarlo vacío es una buena opción predeterminada; utiliza este campo solo si quieres evitar explícitamente un estilo o una dirección concretos.
- `context_adherence` (enum, optional, default: high) — Hasta qué punto el modelo se ajusta al contexto de los fragmentos que lo rodean. Una adherencia baja permite que el modelo se aleje del contexto y sea más creativo. Una adherencia alta hace que el modelo sea más coherente con el contexto.
  - Allowed values: `low`, `medium`, `high`
- `conditioning_ref` (AudioRefChunk, optional, nullable) — La referencia de audio que condicionará la generación. El primer fragmento es el más importante, ya que influirá en la generación de todos los fragmentos posteriores. Por tanto, si quieres aplicar el condicionamiento a toda la canción, empieza por el primer fragmento.
- `condition_strength` (enum, optional, nullable) — Con qué intensidad el modelo se ajusta a la referencia de condicionamiento. Una intensidad baja hace que el modelo sea más creativo y se aleje de la referencia. Una intensidad alta hace que el modelo sea más coherente con la referencia.
  - Allowed values: `low`, `medium`, `high`, `xhigh`

### AudioRefChunk

- `song_id` (string, required) — El ID de la canción de la que se obtendrá el fragmento. Puedes encontrar el ID de la canción en las cabeceras de respuesta al generar una canción.
- `range` (TimeRange, required) — El intervalo de tiempo que se extraerá de la canción.

### 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": "Descripción de mi canción",
    "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()
```