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

# Progetta una voce.

POST https://api.elevenlabs.io/v1/text-to-voice/design
Content-Type: application/json

Progetta una voce tramite un prompt. Questo metodo restituisce un elenco di anteprime vocali. Ogni anteprima contiene un generated_voice_id e un campione della voce come audio MP3 codificato in base64. Per creare una voce, usa il generated_voice_id dell'anteprima scelta con l'endpoint /v1/text-to-voice.

Reference: https://elevenlabs.io/docs/api-reference/text-to-voice/design

## 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) — Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
  - Allowed values: `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 VoiceDesignRequestModel.

- `voice_description` (string, required) — Descrizione da usare per la voce creata.
- `model_id` (enum, optional, default: eleven_multilingual_ttv_v2) — Modello da usare per la generazione vocale. Valori possibili: eleven_multilingual_ttv_v2, eleven_ttv_v3.
  - Allowed values: `eleven_multilingual_ttv_v2`, `eleven_ttv_v3`
- `text` (string, optional, nullable) — Testo da generare; la lunghezza deve essere compresa tra 100 e 1000 caratteri.
- `auto_generate_text` (boolean, optional, default: false) — Indica se generare automaticamente un testo adatto alla descrizione della voce.
- `loudness` (double, optional, default: 0.5) — Controlla il livello del volume della voce generata. -1 è il più basso, 1 è il più alto, 0 corrisponde a circa -24 LUFS.
- `seed` (integer, optional, nullable) — Numero casuale che controlla la generazione della voce. Lo stesso seed con gli stessi input produce la stessa voce.
- `guidance_scale` (double, optional, default: 5) — Controlla quanto fedelmente l'IA segue il prompt. Valori più bassi lasciano all'IA maggiore libertà creativa, mentre valori più alti la vincolano maggiormente al prompt. Valori alti possono far sembrare la voce artificiale o robotica. Ti consigliamo di usare prompt più lunghi e dettagliati con una Guidance Scale più bassa.
- `stream_previews` (boolean, optional, default: false) — Determina se le anteprime di Text to Voice devono essere incluse nella risposta. Se true, vengono restituiti solo gli ID generati, che possono poi essere trasmessi in streaming tramite l'endpoint /v1/text-to-voice/:generated_voice_id/stream.
- `should_enhance` (boolean, optional, default: false) — Indica se migliorare la descrizione della voce con l'IA per aggiungere dettagli e migliorare la qualità della generazione vocale. Se abilitata, il sistema espanderà automaticamente i prompt semplici in descrizioni della voce più dettagliate. Il valore predefinito è False
- `remixing_session_id` (string, optional, nullable) — L'ID della sessione di remix.
- `remixing_session_iteration_id` (string, optional, nullable) — L'ID dell'iterazione della sessione di remix a cui associare queste generazioni. Se non viene fornito, verrà creata una nuova iterazione.
- `quality` (double, optional, nullable) — Una qualità superiore migliora l'output vocale, ma riduce la varietà.
- `reference_audio_base64` (string, optional, nullable) — Audio di riferimento da utilizzare per la generazione della voce. L'audio deve essere codificato in base64. Supportato solo quando si utilizza il modello eleven_ttv_v3.
- `prompt_strength` (double, optional, nullable) — Controlla il bilanciamento tra prompt e audio di riferimento durante la generazione di campioni vocali. 0 indica un'influenza quasi nulla del prompt, 1 un'influenza quasi nulla dell'audio di riferimento. Supportato solo con il modello eleven_ttv_v3.

## Response

### 200

Risposta riuscita

- `previews` (list of VoicePreviewResponseModel, required) — Le anteprime delle voci generate.
- `text` (string, required) — Il testo usato per l'anteprima delle voci.

## Errors

### 409 Conflict Error

È già in corso una generazione per questa anteprima. Riprova la richiesta.

- `any`

### 422 Unprocessable Entity Error

Errore di convalida

- `detail` (list of ValidationError, optional)

## Types

### VoicePreviewResponseModel

- `audio_base_64` (string, required) — L'audio dell'anteprima codificato in base64.
- `generated_voice_id` (string, required) — L'ID della voce generata. Usalo per creare una voce dall'anteprima.
- `media_type` (string, required) — Il tipo di file multimediale dell'anteprima.
- `duration_secs` (double, required) — La durata dell'anteprima in secondi.
- `language` (string, required, nullable) — La lingua dell'anteprima.

### ValidationError

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

### ValidationErrorLocItems

## Examples

**Request**

```json
{
  "voice_description": "A sassy squeaky mouse"
}
```

**Response**

```json
{
  "previews": [
    {
      "audio_base_64": "string",
      "generated_voice_id": "string",
      "media_type": "string",
      "duration_secs": 1.1,
      "language": "string"
    }
  ],
  "text": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/text-to-voice/design"

payload = { "voice_description": "A sassy squeaky mouse" }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/text-to-voice/design';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"voice_description":"A sassy squeaky mouse"}'
};

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/text-to-voice/design"

	payload := strings.NewReader("{\n  \"voice_description\": \"A sassy squeaky mouse\"\n}")

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

	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/text-to-voice/design")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voice_description\": \"A sassy squeaky mouse\"\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/text-to-voice/design")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_description\": \"A sassy squeaky mouse\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/text-to-voice/design', [
  'body' => '{
  "voice_description": "A sassy squeaky mouse"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/text-to-voice/design");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"voice_description\": \"A sassy squeaky mouse\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["voice_description": "A sassy squeaky mouse"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/text-to-voice/design")! 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()
```