> ## Documentation Index
> Fetch the complete documentation index at: https://docs-model.skyengine.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# ElevenLabs 语音合成

> 使用 Eleven v3 生成语音，通过 stability 和表达标签控制语音表现

# ElevenLabs 语音合成

通过 `POST /v1/audio/speech` 调用 `eleven_v3`。生成完成后，平台将音频转存到云存储，返回可下载或播放的 `url`。

Eleven v3 支持多语言语音生成，可通过音色、稳定性和表达标签调整朗读效果。使用前，请确保 API Key 已开通 `eleven_v3` 模型。

## 非流式语音合成

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://model-api.skyengine.com.cn/v1/audio/speech \
    --header 'Authorization: Bearer <API-KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "eleven_v3",
      "input": "欢迎使用 ModelHub 语音合成服务。",
      "voice": "JBFqnCBsd6RMkjVDRZzb",
      "response_format": "mp3",
      "stream": false,
      "model_extra": {
        "voice_settings": { "stability": 0.5 }
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://model-api.skyengine.com.cn/v1/audio/speech",
      headers={"Authorization": "Bearer <API-KEY>"},
      json={
          "model": "eleven_v3",
          "input": "欢迎使用 ModelHub 语音合成服务。",
          "voice": "JBFqnCBsd6RMkjVDRZzb",
          "response_format": "mp3",
          "stream": False,
          "model_extra": {"voice_settings": {"stability": 0.5}},
      },
      timeout=120,
  )
  response.raise_for_status()
  result = response.json()
  print("音频地址:", result["url"])
  print("音频时长（毫秒）:", result.get("duration_ms"))

  # 下载音频时无需附带平台 API Key。
  audio = requests.get(result["url"], timeout=60)
  audio.raise_for_status()
  with open("speech.mp3", "wb") as audio_file:
      audio_file.write(audio.content)
  ```

  ```javascript JavaScript/Node.js theme={null}
  const response = await fetch("https://model-api.skyengine.com.cn/v1/audio/speech", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <API-KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "eleven_v3",
      input: "欢迎使用 ModelHub 语音合成服务。",
      voice: "JBFqnCBsd6RMkjVDRZzb",
      response_format: "mp3",
      stream: false,
      model_extra: { voice_settings: { stability: 0.5 } }
    })
  });

  if (!response.ok) throw new Error(await response.text());

  const result = await response.json();
  console.log("音频地址:", result.url);
  console.log("音频时长（毫秒）:", result.duration_ms);
  ```
</CodeGroup>

响应示例（数值仅作示意）：

```json theme={null}
{
  "request_id": "example-request-id",
  "url": "https://example.com/tts/speech.mp3",
  "duration_ms": 3200,
  "token": 23
}
```

| 字段            | 说明                              |
| ------------- | ------------------------------- |
| `request_id`  | 本次语音合成请求的标识，可用于问题排查。            |
| `url`         | 平台转存后的音频访问地址。需要长期保存时，请下载到自己的存储。 |
| `duration_ms` | 音频时长，单位为毫秒。无法计算时不返回。            |
| `token`       | 本次语音生成的字符计费用量，可能与输入字符串长度不同。     |

查询用量时，使用响应头 `x-model-service-trace-id` 的值作为 `GET /v1/usage?request_id=...` 的查询参数。该值与响应正文中的 `request_id` 含义不同。

## 请求参数

| 参数                                     | 类型      | 必填 | 说明                                                                                   |
| -------------------------------------- | ------- | -- | ------------------------------------------------------------------------------------ |
| `model`                                | string  | 是  | 使用 `eleven_v3`。                                                                      |
| `input`                                | string  | 是  | 合成文本；情绪和表达标签也写在此字段中。                                                                 |
| `voice`                                | string  | 是  | 音色 ID，用于选择朗读声音，例如 `JBFqnCBsd6RMkjVDRZzb`。                                            |
| `response_format`                      | string  | 否  | 默认 `mp3`。也支持 `pcm`，默认对应 24 kHz、16-bit、单声道裸 PCM；可使用 `mp3_22050_32`、`pcm_16000` 等完整格式。 |
| `stream`                               | boolean | 否  | 默认 `false`，当前仅支持非流式生成。                                                               |
| `model_extra.voice_settings.stability` | number  | 否  | 建议显式指定 `0`、`0.5` 或 `1`，见下方三档说明。                                                      |
| `model_extra.seed`                     | integer | 否  | 范围 0–4294967295，用于尽力复现；相同 seed 不保证生成完全相同的音频。                                         |

<Note>
  非流式响应是包含音频 URL 的 JSON，不是音频二进制。裸 PCM 不含文件头，播放或封装为 WAV 时需要使用请求对应的采样率、位深和声道数。
</Note>

## 选择音色

`model` 决定使用哪个语音生成模型，`voice` 决定使用哪个声音朗读。示例中的 `JBFqnCBsd6RMkjVDRZzb` 是音色的唯一标识；更换声音时，将其替换为已开通的 ElevenLabs 音色 ID。

## Stability：控制表达与稳定性

| 值     | 档位       | 表现倾向                        |
| ----- | -------- | --------------------------- |
| `0`   | Creative | 更有表现力，生成变化较大，也更容易出现偏离文本的表达。 |
| `0.5` | Natural  | 自然、均衡，适合作为起点。               |
| `1`   | Robust   | 更稳定，但对情绪和表达标签的响应可能较弱。       |

通过 `model_extra.voice_settings.stability` 选择档位。例如，以下 `model_extra` 配置使用 Natural：

```json theme={null}
{
  "voice_settings": {
    "stability": 0.5
  },
  "seed": 41022
}
```

日常配音可从 `0.5` 开始；需要更丰富的情绪时使用 `0`，需要更平稳的朗读时使用 `1`。

## 情绪和表达标签

将标签写在 `input` 中需要调整表达的文本前。搭配 `stability: 0` 或 `0.5`，更有利于表现情绪。

| 表达   | input 示例                           |
| ---- | ---------------------------------- |
| 自然表达 | `我刚刚收到一条消息。我们的计划终于成功了！`            |
| 耳语   | `[whispers] 我刚刚收到一条消息。我们的计划终于成功了！` |
| 兴奋   | `[excited] 我刚刚收到一条消息。我们的计划终于成功了！`  |
| 笑声   | `[laughs] 我刚刚收到一条消息。我们的计划终于成功了！`   |

完整调用示例：

```bash theme={null}
curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/audio/speech \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "eleven_v3",
    "input": "[excited] 我刚刚收到一条消息。我们的计划终于成功了！先别告诉其他人，等大家到齐，我们再一起宣布这个好消息。",
    "voice": "JBFqnCBsd6RMkjVDRZzb",
    "response_format": "mp3",
    "stream": false,
    "model_extra": {
      "voice_settings": { "stability": 0.5 },
      "seed": 41022
    }
  }'
```

标签的表现随音色、文本和 stability 而变化，建议选择与目标表达相适应的音色。标签属于输入内容，会参与用量计算。

## 使用限制

* 当前仅支持非流式生成，`stream: true` 和 WAV 输出会返回参数错误。
* 当前 Eleven v3 接口不提供数值语速、音色相似度和 Speaker Boost 调节，请使用本页介绍的音色、stability 和表达标签。
* 不支持通过前后文文本或请求 ID 拼接音频。

更多表达方法可参考 [Eleven v3 官方提示指南](https://elevenlabs.io/docs/overview/capabilities/text-to-speech/best-practices#prompting-eleven-v3)。