山间茶馆的第一壶茶 — 温和的中文迎宾词,中间带一声轻笑。
ElevenLabs V4 Text to Speech API
elevenlabs/tts/eleven-v4ElevenLabs V4 Text to Speech 将文稿转为富有情感的旁白与角色演绎,支持行内音频标签和90多种语言。按场景调整稳定性与音色相似度,并输出 MP3、PCM、Opus 或电话音频。
输入
示例
ElevenLabs V4 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-v4",
"input": {
"text": "[calm] Night three at the lighthouse. The fog rolled in early, thick as wool. [whispers] At midnight, something knocked on the door... three slow knocks. [nervous laugh] I told myself it was only the wind. [quietly] Then I found wet footprints on the stairs, leading up, and never back down.",
"voice": "George",
"stability": 0.45,
"similarity_boost": 0.75,
"output_format": "mp3_44100_128",
"apply_text_normalization": "auto",
"timestamps": false,
"language_code": "en"
}
}
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": "BAMMBL0SN12PBO8U",
"status": "not_started",
"created_time": "2026-11-05T07:13:33"
}
}{
"code": 200,
"data": {
"task_id": "BAMMBL0SN12PBO8U",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v4/v2/01/speech-01.mp3",
"file_type": "audio",
"file_name": "speech-01.mp3"
}
],
"created_time": "2026-11-05T07:13:33",
"error_message": null,
"progress": 100
}
}获取音频文件
使用音频 file_url 播放或下载。开启 timestamps 时,从单独的 files 条目下载时间文件。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "elevenlabs/tts/eleven-v4",
"input": {
"text": "[calm] Night three at the lighthouse. The fog rolled in early, thick as wool. [whispers] At midnight, something knocked on the door... three slow knocks. [nervous laugh] I told myself it was only the wind. [quietly] Then I found wet footprints on the stairs, leading up, and never back down.",
"voice": "George",
"stability": 0.45,
"similarity_boost": 0.75,
"output_format": "mp3_44100_128",
"apply_text_normalization": "auto",
"timestamps": false,
"language_code": "en"
}
}
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-v4 选择该语音模型。 |
| input | object | 是 | — | 包含文稿及下列语音控制参数。 |
| input.text | string | 是 | — | 要朗读的文稿,按原样计数为1–5,000个字符,空格、换行和音频标签均计入。在语气需要变化的位置加入 [whispers]、[excited] 等标签。 |
| input.voice | string | 否 | Rachel | ElevenLabs 音色名称或音色 ID。可选择 Rachel、George、Lily 等推荐预设,也可以填入其他 ElevenLabs 音色的 ID。 |
| input.stability | number | 否 | 0.5 | 取值0–1。数值越低,表达变化越丰富;数值越高,各句之间的语气越平稳。 |
| input.similarity_boost | number | 否 | 0.75 | 取值0–1,设置语音与所选音色特征的贴近程度。 |
| input.output_format | string | 否 | mp3_44100_128 | 返回音频的编码、采样率与码率:22.05或44.1 kHz 的 MP3、8–48 kHz 的原始 PCM、适合电话场景的8 kHz µ-law 与 A-law,以及48 kHz 的 Opus。 可选值:mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192, pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192. |
| input.apply_text_normalization | string | 否 | auto | auto 自动判断何时把数字、日期和符号转成读法,on 始终规范化,off 按你已写成口语的文本直接朗读。 |
| input.timestamps | boolean | 否 | false | 设为 true 时,额外返回一个记录语音时间信息的文件,与音频一同提供。 |
| input.language_code | string | 否 | — | 可选的 ISO 639-1 语言代码,如 en、zh 或 es,用于指定朗读语言;留空时由模型根据文稿识别语言。 |
| 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 表示时间文件等附件。 |
| 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字符 | 按提交原文计数,包括空格和标签。 |
| 语言 | 90+ | 根据文稿识别,或通过 language_code 指定。 |
| 输出格式 | 19种 | MP3、PCM、µ-law、A-law 与 Opus;默认 mp3_44100_128。 |
| 价格 | $0.08 / 1K 字符 | 每1,000字符16 credits。 |
| 时间数据 | 可选 | timestamps 为 true 时作为额外文件返回。 |
ElevenLabs V4 Text to Speech API 常见问题
ElevenLabs V4 Text to Speech API 是什么?
ElevenLabs V4 Text to Speech 是 ElevenLabs 用于将文稿转为富有表现力语音的模型。它可以用90多种语言生成旁白和角色台词,并通过行内音频标签控制情绪、停顿和反应。模型结合标签、标点与上下文理解演绎意图,同时由你控制音色、稳定性、相似度和输出格式。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
ElevenLabs V4 与 ElevenLabs V3 有什么区别?
ElevenLabs V4 是2026年9月发布的新一代模型,支持90多种语言,V3 为70多种。在 Vidgo 上,V4 还新增 Similarity Boost、19种输出格式,以及预设列表之外的音色 ID,价格仍为每千字符16 credits($0.08)。
ElevenLabs V4 如何使用音频标签?
在 Text 中用方括号写入演绎指令,如 [whispers]、[laughs] 或 [excited],放在需要影响的词句之前。标签计入字符数。建议每个短语先用一个标签,试听后再增加。
ElevenLabs V4 一次能处理多长的文稿?
每次请求接受1–5,000个字符,按提交原文计数,包括空格、换行和标签。更长的文稿请按段落或场景拆分,并在各部分沿用相同的音色设置。
ElevenLabs V4 支持哪些输出格式?
Output Format 提供19个取值:22.05或44.1 kHz、32–192 kbps 的 MP3,8–48 kHz 的原始 PCM,8 kHz 的 µ-law 与 A-law,以及48 kHz、32–192 kbps 的 Opus。默认值为 mp3_44100_128。
ElevenLabs V4 可以使用我自己的 ElevenLabs 音色吗?
Voice 接受 ElevenLabs 音色名称或音色 ID。可使用 Rachel、George 等推荐预设,也可以粘贴其他 ElevenLabs 音色的 ID,并在对比时保持 Stability 与 Similarity Boost 不变。
ElevenLabs V4 能返回用于字幕的时间戳吗?
可以。将 timestamps 设为 true,任务完成后 files 中会在音频之外额外包含一个时间文件,可用于放置字幕或对齐剪辑。
ElevenLabs V4 每次请求费用是多少?
ElevenLabs V4 每1,000字符收费16 credits($0.08)。1,000字符的文稿为16 credits,完整的5,000字符请求为80 credits($0.40)。


