> ## Documentation Index
> Fetch the complete documentation index at: https://quwan-b8010aef.mintlify.site/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` 模型。

## 非流式语音合成

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

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

response = requests.post(
    "https://api.tokenops.ai/v1/audio/speech",
    headers={"Authorization": "Bearer <API-KEY>"},
    json={
        "model": "eleven_v3",
        "input": "欢迎使用 TokenOPS.AI 语音合成服务。",
        "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://api.tokenops.ai/v1/audio/speech", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API-KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "eleven_v3",
    input: "欢迎使用 TokenOPS.AI 语音合成服务。",
    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);
```

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

```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` 含义不同。

## 流式语音合成

设置 `stream: true` 后，接口通过 SSE 返回音频块。每个事件的 `audio` 是一段独立 Base64 编码的音频数据；按接收顺序逐段解码并写入同一个文件。流结束前会返回包含 `token` 的用量事件。

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

with requests.post(
    "https://api.tokenops.ai/v1/audio/speech",
    headers={"Authorization": "Bearer <API-KEY>"},
    json={
        "model": "eleven_v3",
        "input": "欢迎使用 TokenOPS.AI 流式语音合成服务。",
        "voice": "JBFqnCBsd6RMkjVDRZzb",
        "response_format": "mp3",
        "stream": True,
        "model_extra": {"voice_settings": {"stability": 0.5}},
    },
    stream=True,
    timeout=120,
) as response:
    response.raise_for_status()
    with open("speech.mp3", "wb") as audio_file:
        for line in response.iter_lines(decode_unicode=True):
            if not line or not line.startswith("data: "):
                continue
            event = json.loads(line[6:])
            if event.get("error"):
                raise RuntimeError(event["error"]["message"])
            if event.get("audio"):
                audio_file.write(base64.b64decode(event["audio"]))
            if event.get("token"):
                print("字符用量:", event["token"])
```

### SSE 响应示例

成功响应的 `Content-Type` 为 `text/event-stream`。一次响应通常包含多个音频事件和一个末尾用量事件，例如：

```text theme={null}
data: {"audio":"SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYwLjMuMTAw..."}

data: {"audio":"//uQZAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."}

data: {"token":23}

```

每个事件均以 `data: ` 开头，并以一个空行结束。最后一个事件发送完成后服务器关闭连接；接口不发送 `[DONE]` 标记。

| 字段 | 类型 | 说明 |
| - | - | - |
| `audio` | string | 当前音频块的 Base64 编码。每个块需要独立解码，再按事件接收顺序拼接二进制数据。用量事件不包含此字段。 |
| `token` | integer | 厂商返回的字符计费用量。正常情况下仅在音频发送结束时出现一次；音频事件不包含此字段。 |
| `error` | object | 流已经建立后发生错误时返回，出现后本次流结束。正常事件不包含此字段。 |
| `error.code` | integer | 平台错误码。 |
| `error.message` | string | 错误说明，可用于问题排查。 |

流式响应不会生成云存储 URL，也不包含非流式响应中的 `url`、`duration_ms` 或正文 `request_id`。使用响应头 `x-model-service-trace-id` 关联日志，并作为 `GET /v1/usage?request_id=...` 的查询参数。

> [!NOTE]
>
> 示例中的 Base64 内容已截断，不能直接作为音频播放。不要拼接 Base64 字符串后再统一解码，应逐块解码后拼接字节。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `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`。设为 `true` 时通过 SSE 返回 Base64 音频块。 |
| `model_extra.voice_settings.stability` | number | 否 | 建议显式指定 `0`、`0.5` 或 `1`，见下方三档说明。 |
| `model_extra.seed` | integer | 否 | 范围 0–4294967295，用于尽力复现；相同 seed 不保证生成完全相同的音频。 |

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

## 选择音色

`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://api.tokenops.ai/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 而变化，建议选择与目标表达相适应的音色。标签属于输入内容，会参与用量计算。

## 使用限制

* WAV 输出会返回参数错误；流式输出请使用 MP3、PCM、Opus、μ-law 或 A-law。
* 当前 Eleven v3 接口不提供数值语速、音色相似度和 Speaker Boost 调节，请使用本页介绍的音色、stability 和表达标签。
* 不支持通过前后文文本或请求 ID 拼接音频。

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.