第一次包好饺子 — 自然的中文口语节奏,带着犹疑、笑意和生活中的温暖。
ElevenLabs V3 Text to Speech API
elevenlabs/tts/eleven-v3ElevenLabs V3 Text to Speech 将文稿转为情感丰富的语音,支持音频标签与70多种语言。通过文本引导语气、停顿和情绪变化,配合稳定性设置塑造旁白与角色演绎。
输入
示例
ElevenLabs V3 Text to Speech API
通过 API 生成语音
提交文稿并保存返回的 task_id,通过任务状态接口获取完成后的音频。
设置请求认证
在 Authorization 请求头中使用 Bearer 方式传入 Vidgo API 密钥。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer YOUR_API_KEY
提交文稿
以 JSON 提交 model 与 input。下方示例使用第一段音频样例的文稿与音色。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "elevenlabs/tts/eleven-v3",
"input": {
"text": "[whispers] Wait... that ticking is coming from inside the wall. [curious] This little brass key fits the crack. One turn, and... [excited] the whole ceiling is full of stars! [laughs] Grandpa, you built a planetarium in the attic. [exhales] All these years, it was waiting for us.",
"voice": "Charlotte",
"language_code": "en",
"stability": 0.5,
"timestamps": false,
"apply_text_normalization": "auto"
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"查询任务
使用返回的 task_id 查询,直至 status 为 finished 或 failed。
状态接口
GET https://api.vidgo.ai/api/generate/status/{task_id}保存提交时返回的 task_id,查询其状态,并在完成后读取生成文件。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "LPV36KJQ0Y2SYT21",
"status": "not_started",
"created_time": "2026-09-27T10:45:57"
}
}{
"code": 200,
"data": {
"task_id": "LPV36KJQ0Y2SYT21",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/01/speech.mp3",
"file_type": "audio",
"file_name": "speech.mp3"
}
],
"created_time": "2026-09-27T10:45:57",
"error_message": null,
"progress": 100
}
}获取音频文件
使用音频 file_url 播放或下载。请求时间戳时,从 other 文件条目下载 timestamps.json。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "elevenlabs/tts/eleven-v3",
"input": {
"text": "[whispers] Wait... that ticking is coming from inside the wall. [curious] This little brass key fits the crack. One turn, and... [excited] the whole ceiling is full of stars! [laughs] Grandpa, you built a planetarium in the attic. [exhales] All these years, it was waiting for us.",
"voice": "Charlotte",
"language_code": "en",
"stability": 0.5,
"timestamps": false,
"apply_text_normalization": "auto"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
语音控制参数填写在 input 内,model 与 callback_url 位于请求顶层。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 使用 elevenlabs/tts/eleven-v3 选择此语音模型。 |
| input | object | 是 | — | 包含下列文稿与语音控制参数。 |
| input.text | string | 是 | — | 输入去除首尾空白后为1至5,000字符的文稿。在文字中加入 [whispers] 或 [excited] 等音频标签,引导演绎方式。 |
| input.voice | string | 否 | Rachel | 从21个预设音色中选择,用一小段文稿试听,找到适合旁白或角色的声音。可选音色:Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill, Rachel。 |
| input.stability | number | 否 | 0.5 | 取值为0至1。较低设置偏向丰富的演绎变化,较高设置偏向平稳表达。建议从0.5开始,用同一段文稿比较。 |
| input.timestamps | boolean | 否 | false | 设为 true 时请求时间对齐数据,结果会在音频之外附带独立的 timestamps.json 文件。 |
| input.language_code | string | 否 | — | 可填写 en、zh、es 等 ISO 639-1 语言代码指定朗读语言;留空时自动识别文本语言。 |
| input.apply_text_normalization | string | 否 | auto | 选择 auto 自动处理文本规范化,on 开启处理,off 用于已按朗读方式整理好的文稿。文本规范化有助于将数字与符号转成口语表达。 |
| callback_url | string | 否 | — | 可选的 HTTP 或 HTTPS 任务通知地址,填写在请求顶层。 |
响应字段
提交响应提供任务标识,状态响应用于跟踪语音生成直至完成。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 响应代码,成功响应使用200或0。 |
| data.task_id | string | 用于查询状态的任务标识。 |
| data.status | string | 任务状态:not_started、running、finished 或 failed。 |
| data.created_time | string | 服务返回的任务创建时间。 |
| data.files | array | 生成文件列表,audio 条目为语音,other 条目为请求的附件。 |
| data.files[].file_url | string | 用于播放或下载生成文件的地址。 |
| data.files[].file_type | string | audio 表示语音;other 表示 timestamps.json 等附件。 |
| data.files[].file_name | string | 返回的文件名,如有。 |
| data.error_message | string | null | 任务失败时的错误详情。 |
任务生命周期
根据任务状态决定继续查询或读取结果。
not_started任务已接收,等待开始。
running正在生成语音,继续查询当前任务。
finished生成完成,从 files 获取音频与请求的附件。
failed生成失败,查看 error_message 后决定是否重新提交。
处理结果与中断
- 保留当前任务标识状态查询中断时,使用同一 task_id 再次查询,获取最新状态。
- 按用途读取文件通过 file_type 区分语音与附件,使用各条目返回的 file_url 与 file_name 下载文件。
- 检查失败任务status 为 failed 时,查看 error_message,检查文稿与设置后再提交生成。
语音规格
| 项目 | 规格 | 说明 |
|---|---|---|
| 任务 | Text to Speech | 根据文稿与选定音色生成语音。 |
| 文本长度 | 1–5,000字符 | 按去除首尾空白后的文本计算。 |
| 音色 | 21个预设 | 通过 input.voice 选择音色。 |
| 语言 | 70+ | 自动识别,或用 language_code 指定语言。 |
| 时间对齐数据 | timestamps.json | 将 timestamps 设为 true 时请求。 |
探索更多音频模型
ElevenLabs V3 Text to Speech API 常见问题
ElevenLabs V3 Text to Speech API 是什么?
ElevenLabs V3 Text to Speech 是 ElevenLabs 用于将文稿转为富有情感的语音的模型。它支持音频标签与70多种语言,可制作旁白和角色台词。模型结合标签、标点与叙事上下文理解表达意图,让你围绕选定音色引导语气,并用稳定性设置调整演绎。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
ElevenLabs V3 如何使用音频标签?
在 Text 中用方括号写入演绎指令,例如在揭晓结果前加入 [excited],在轻声台词前加入 [whispers]。将标签放在语气需要变化的位置,并保持前后句子自然连贯。先用一个明确指令试听,再调整措辞或音色。
ElevenLabs V3 能演绎低语与笑声吗?
可以。使用 [whispers]、[laughs]、[sighs] 等标签,可以引导低语、笑声与叹息。选择适合场景的音色,并将提示放在相关台词旁,让声音反应有明确的叙事上下文。
ElevenLabs V3 支持哪些语言?
ElevenLabs V3 支持70多种语言,包括英语、普通话、西班牙语、法语、日语和韩语。输入目标语言文稿,可通过 Language Code 填写 en 或 zh 等代码指定语言。制作多语言版本时,分别提供各语言的译稿,并试听选定音色。
ElevenLabs V3 的稳定性如何影响语音?
Stability 用于调整演绎变化与平稳表达之间的取向。可从0.5开始,在0至1范围内,为生动角色比较较低设置,为沉稳旁白比较较高设置。对比时固定文稿与音色,便于判断设置带来的变化。
ElevenLabs V3 的长文稿如何分段?
每次请求控制在5,000字符以内,包含文稿中的音频标签、标点与内部空格。按段落或场景边界拆分,让每段保有演绎所需的上下文。沿用相同音色与语言设置,并在组合音频时检查段落衔接。
ElevenLabs V3 如何朗读数字?
文本规范化有助于将书面数字与符号转成口语表达。将 Apply Text Normalization 设为 auto 自动处理,或设为 on 开启规范化。先用包含日期或金额的短段落试听;需要特定读法时,可直接将文字写成目标朗读形式。
ElevenLabs V3 能返回时间戳吗?
可以。开启 Timestamps 后,生成语音时会同时请求时间对齐数据。完成结果中包含独立的 timestamps.json 附件,可与音频一起下载,用于字幕或剪辑时的时间对齐参考。















