ElevenLabs 语音合成

通过 POST /v1/audio/speech 调用 eleven_v3。生成完成后，平台将音频转存到云存储，返回可下载或播放的 url。 Eleven v3 支持多语言语音生成，可通过音色、稳定性和表达标签调整朗读效果。使用前，请确保 API Key 已开通 eleven_v3 模型。

非流式语音合成

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 }
    }
  }'

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)

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);

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

{
  "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

import base64
import json
import requests

with 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": 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。一次响应通常包含多个音频事件和一个末尾用量事件，例如：

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=... 的查询参数。

示例中的 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 不保证生成完全相同的音频。

非流式响应是包含音频 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：

{
  "voice_settings": {
    "stability": 0.5
  },
  "seed": 41022
}

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

情绪和表达标签

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

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

完整调用示例：

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

使用限制

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

更多表达方法可参考 Eleven v3 官方提示指南。

API端点参考

使用示例

ElevenLabs 语音合成

ElevenLabs 语音合成

非流式语音合成

流式语音合成

SSE 响应示例

请求参数

选择音色

Stability：控制表达与稳定性

情绪和表达标签

使用限制

​ElevenLabs 语音合成

​非流式语音合成

​流式语音合成

​SSE 响应示例

​请求参数

​选择音色

​Stability：控制表达与稳定性

​情绪和表达标签

​使用限制

ElevenLabs 语音合成

非流式语音合成

流式语音合成

SSE 响应示例

请求参数

选择音色

Stability：控制表达与稳定性

情绪和表达标签

使用限制