xAI TTS 1 Text to Speech API
xai/tts/v1xAI TTS 1 Text to Speech 将文稿转为多语言配音,提供五种音色与语音标签。用行内标记安排停顿和笑声,用包裹式标签引导段落低语与朗读节奏。
xAI TTS 1 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": "xai/tts/v1",
"input": {
"text": "Welcome to our story. [pause] <whisper>Listen closely.</whisper> [laugh] Let us begin.",
"voice": "eve",
"language_code": "auto",
"output_format": {
"codec": "mp3",
"sample_rate": 24000,
"bit_rate": 128000
}
}
}
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": "your_task_id",
"status": "not_started",
"created_time": "2026-09-27T10:00:00"
}
}{
"code": 200,
"data": {
"task_id": "your_task_id",
"status": "finished",
"files": [
{
"file_url": "https://example.com/generated-speech.mp3",
"file_type": "audio",
"file_name": "speech.mp3"
}
],
"error_message": null,
"progress": 100
}
}获取音频文件
读取 file_type 为 audio 的 files 条目,使用 file_url 下载语音。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "xai/tts/v1",
"input": {
"text": "Welcome to our story. [pause] <whisper>Listen closely.</whisper> [laugh] Let us begin.",
"voice": "eve",
"language_code": "auto",
"output_format": {
"codec": "mp3",
"sample_rate": 24000,
"bit_rate": 128000
}
}
}
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 | 是 | — | 将 model 设为 xai/tts/v1。 |
| input | object | 是 | — | 包含下列文稿与语音控制参数。 |
| input.text | string | 是 | — | 输入去除首尾空白后 1–15,000 个字符的文稿。通过 [laugh]、[pause]、[sigh]、<whisper>text</whisper> 或 <slow>text</slow> 引导语音表现。 |
| input.voice | string | 否 | eve | 为旁白或角色选择 eve、ara、rex、sal 或 leo,默认 eve。 |
| input.language_code | string | 否 | auto | 选择列表中的 BCP-47 语言代码,或使用 auto 自动识别语言。 auto, en, ar-EG, ar-SA, ar-AE, bn, zh, fr, de, hi, id, it, ja, ko, pt-BR, pt-PT, ru, es-MX, es-ES, tr, vi |
| input.output_format | object | 否 | — | 包含 codec、sample_rate 及 MP3 bit_rate 设置的对象。 |
| input.output_format.codec | string | 否 | mp3 | 音频编码格式:mp3、wav、pcm、mulaw 或 alaw,默认 mp3。 |
| input.output_format.sample_rate | integer | 否 | 24000 | 采样率,单位 Hz:8000、16000、22050、24000、44100 或 48000,默认 24000。 |
| input.output_format.bit_rate | integer | null | 否 | 128000 (mp3) | MP3 比特率,单位 bit/s:32000、64000、96000、128000、192000 或 null,MP3 默认 128000。使用 wav、pcm、mulaw 或 alaw 时省略 bit_rate 或设为 null。 |
| 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 | 生成的语音文件。 |
| data.files[].file_url | string | 用于播放或下载生成文件的地址。 |
| data.files[].file_type | string | 生成语音的类型为 audio。 |
| data.files[].file_name | string | 返回的文件名,如有。 |
| data.error_message | string | null | 任务失败时的错误详情。 |
任务生命周期
根据任务状态决定继续查询或读取结果。
not_started任务已接收,等待开始。
running正在生成语音,继续查询当前任务。
finished生成完成,从 files 获取语音文件。
failed生成失败,查看 error_message 后决定是否重新提交。
处理结果与中断
- 保留当前任务标识状态查询中断时,使用同一 task_id 再次查询,获取最新状态。
- 读取音频结果使用每个 audio 条目的 file_url 和 file_name 下载语音。
- 检查失败任务status 为 failed 时,查看 error_message,检查文稿与设置后再提交生成。
语音规格
| 项目 | 规格 | 说明 |
|---|---|---|
| 任务 | Text to Speech | 通过文本和所选音色生成语音。 |
| 文本长度 | 1–15,000 | 去除首尾空白后的 Unicode 字符数。 |
| 音色 | eve, ara, rex, sal, leo | 通过 input.voice 选择预设音色。 |
| 语言 | auto, en, ar-EG, ar-SA, ar-AE, bn, zh, fr, de, hi, id, it, ja, ko, pt-BR, pt-PT, ru, es-MX, es-ES, tr, vi | 选择语言代码或 auto。 |
| 输出 | mp3, wav, pcm, mulaw, alaw | 通过 output_format 设置编码和采样率。 |
xAI TTS 1 Text to Speech API 常见问题
xAI TTS 1 Text to Speech API 是什么?
xAI TTS 1 Text to Speech 是 xAI 用于将文稿转为旁白和角色台词的语音生成模型。它提供五种音色、多语言朗读和文本内语音标签,适合故事配音与课程制作。行内标签控制局部停顿和表情声音,包裹式标签引导指定段落的低语或慢速表达。你可以通过 API 进行程序化调用,也可以在体验区标签页直接在线试用。
xAI TTS 1 可以选择哪些音色?
Voice 提供 eve、ara、rex、sal 和 leo,默认 eve。用同一段台词试听这些声音,再为旁白或角色选择合适的音色。
xAI TTS 1 如何使用行内语音标签?
在 Text 中需要停顿、笑声或叹息的位置加入 [pause]、[laugh] 或 [sigh]。标签紧邻对应台词,便于试听后逐句调整表达。
xAI TTS 1 如何使用包裹式标签?
用 <whisper>台词</whisper> 引导低语,用 <slow>台词</slow> 引导慢速朗读。成对标签包裹需要调整的文字,可将同一文稿中的不同段落分别处理。
xAI TTS 1 如何选择朗读语言?
Language Code 可设为 auto 自动识别,也可选择 zh、en、ja 等语言代码。葡萄牙语、西班牙语和阿拉伯语提供列表中的地区选项,按文稿选择对应代码。
xAI TTS 1 接受多长的文稿?
每次接受去除首尾空白后 1–15,000 个 Unicode 字符,文稿内的标签、标点和空格均计入长度。长篇内容可按段落拆分,并沿用相同音色、语言和输出设置。
xAI TTS 1 提供哪些音频格式?
Output Format.Codec 提供 mp3、wav、pcm、mulaw 和 alaw。MP3 与 WAV 可在页面试听,PCM、mulaw 和 alaw 可下载后用于音频系统;采样率从参数说明列出的档位中选择。
xAI TTS 1 如何设置 MP3 码率?
选择 mp3 后,在 Output Format.Bit Rate 中选择 32000、64000、96000、128000 或 192000,单位为 bit/s,默认 128000。使用其他编码时省略 bit_rate 或设为 null,音频规格由编码与采样率确定。