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

# 设计音色。

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

通过提示词设计音色。此方法会返回音色预览列表。每个预览都包含 generated_voice_id，以及以 base64 编码的 mp3 音频形式提供的音色样本。要创建音色，请通过 /v1/text-to-voice 端点使用所选预览的 generated_voice_id。

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) — 生成音频的输出格式。格式为 codec_sample_rate_bitrate。因此，采样率为 22.05kHz、比特率为 32kbs 的 mp3 表示为 mp3_22050_32。使用 192kbps 比特率的 MP3 需要订阅 Creator 或更高版本。采样率为 44.1kHz 的 PCM 格式需要订阅 Pro 或更高版本。请注意，μ-law 格式（有时写作 mu-law，通常近似写作 u-law）常用于 Twilio 音频输入。
  - 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) — 用于创建音色的说明。
- `model_id` (enum, optional, default: eleven_multilingual_ttv_v2) — 用于语音生成的模型。可选值：eleven_multilingual_ttv_v2、eleven_ttv_v3。
  - Allowed values: `eleven_multilingual_ttv_v2`, `eleven_ttv_v3`
- `text` (string, optional, nullable) — 要生成的文本，长度必须在 100 到 1000 之间。
- `auto_generate_text` (boolean, optional, default: false) — 是否自动生成适合音色描述的文本。
- `loudness` (double, optional, default: 0.5) — 控制生成语音的音量级别。-1 最安静，1 最响，0 大致对应 -24 LUFS。
- `seed` (integer, optional, nullable) — 控制语音生成的随机数。相同种子和相同输入会生成相同的语音。
- `guidance_scale` (double, optional, default: 5) — Controls how closely the AI follows the prompt. Lower numbers give the AI more freedom to be creative, while higher numbers force it to stick more to the prompt. High numbers can cause voice to sound artificial or robotic. We recommend to use longer, more detailed prompts at lower Guidance Scale.
- `stream_previews` (boolean, optional, default: false) — 决定响应中是否包含文本转语音预览。如果为 true，则仅返回生成的 ID，之后可通过 /v1/text-to-voice/:generated_voice_id/stream 端点进行流式传输。
- `should_enhance` (boolean, optional, default: false) — 是否使用 AI 增强声音描述，以补充更多细节并提升语音生成质量。启用后，系统会自动将简单提示词扩展为更详细的声音描述。默认为 False。
- `remixing_session_id` (string, optional, nullable) — 混音会话 ID。
- `remixing_session_iteration_id` (string, optional, nullable) — 这些生成内容要附加到的混音会话迭代 ID。未提供时，将创建新的迭代。
- `quality` (double, optional, nullable) — 更高质量可带来更好的语音输出，但多样性较低。
- `reference_audio_base64` (string, optional, nullable) — 用于语音生成的参考音频。音频应采用 base64 编码。仅使用 eleven_ttv_v3 模型时支持。
- `prompt_strength` (double, optional, nullable) — 控制生成音频样本时提示词与参考音频的权重。0 表示提示词几乎没有影响，1 表示参考音频几乎没有影响。仅在使用 eleven_ttv_v3 模型时支持。

## Response

### 200

成功响应

- `previews` (list of VoicePreviewResponseModel, required) — 生成音色的预览。
- `text` (string, required) — 用于预览音色的文本。

## Errors

### 409 Conflict Error

此预览的生成已在进行中。请重试请求。

- `any`

### 422 Unprocessable Entity Error

验证错误。

- `detail` (list of ValidationError, optional)

## Types

### VoicePreviewResponseModel

- `audio_base_64` (string, required) — 预览音频的 base64 编码。
- `generated_voice_id` (string, required) — 生成音色的 ID。可使用它从预览创建音色。
- `media_type` (string, required) — 预览的媒体类型。
- `duration_secs` (double, required) — 预览时长，单位为秒。
- `language` (string, required, nullable) — 预览的语言。

### ValidationError

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

### ValidationErrorLocItems

- string
- integer

## 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()
```