> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# xAI TTS 1
> 使用 xAI TTS 将文本转换为语音，可从五种音色和多种语言中选择，适用于旁白、对话和口播内容。
> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。
使用 xAI TTS 将文本转换为语音，可从五种音色和多种语言中选择，适用于旁白、对话和口播内容。
## 模型
* **xai/tts/v1** - 将文本转换为语音。
## 功能
* 将文本转换为语音。
* 使用 `voice` 选择音色，使用 `language_code` 指定朗读语言。
* 通过 `text` 中的标签控制停顿、笑声、叹息、耳语和放慢语速。
## 输出选项
### 输出格式
* `output_format`：可选。传入包含以下字段的对象。
* `output_format.codec`：可选。可选值：`mp3`、`wav`、`pcm`、`mulaw`、`alaw`。默认：`mp3`。
* `output_format.sample_rate`：可选。采样率（Hz）。可选值：`8000`、`16000`、`22050`、`24000`、`44100`、`48000`。默认：`24000`。
* `output_format.bit_rate`：可选。MP3 比特率（bit/s）。可选值：`32000`、`64000`、`96000`、`128000`、`192000`、`null`。MP3 默认：`128000`。
* `mp3` 使用 `output_format.bit_rate` 选择比特率。`wav`、`pcm`、`mulaw` 和 `alaw` 请省略 `bit_rate` 或设为 `null`。
## 高级参数
在请求根级设置 `model` 和可选的 `callback_url`。所有工作流程参数（包括输出选项）都放在 `input` 中。
### 文本
* `text`：必填。要朗读的文本。长度：**1-15,000 个字符**。
* 长度按去除首尾空白后的文本计算。文本中的标签、标点和空格都计入长度。
* 在需要的位置加入 `[laugh]`、`[pause]` 或 `[sigh]`。耳语段落使用 `text`，放慢语速使用 `text`。
### 音色
* `voice`：可选。选择音色。可选值：`eve`、`ara`、`rex`、`sal`、`leo`。默认：`eve`。
### 语言代码
* `language_code`：可选。字符串。默认：`auto`。
> [accordion] 支持的语言代码
>
> * `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`
## 输出文件
* 读取返回的 `files` 数组中的每一项。
* 生成的音频 `file_type` 为 `"audio"`。
* 使用 `file_url` 下载生成的语音。
## 请求示例
```json theme={null}
{
"model": "xai/tts/v1",
"input": {
"text": "Welcome to our story. [pause] Listen closely. [laugh] Let us begin.",
"voice": "eve",
"language_code": "auto",
"output_format": {
"codec": "mp3",
"sample_rate": 24000,
"bit_rate": 128000
}
}
}
```
## OpenAPI
````yaml zh/api-manual/music-series/xai-tts-v1.json POST /api/generate/submit
openapi: 3.0.0
info:
title: Vidgo API - xAI TTS 1
description: 使用 xAI TTS 将文本转换为语音，可从五种音色和多种语言中选择，适用于旁白、对话和口播内容。
version: 1.0.0
servers:
- url: https://api.vidgo.ai
security:
- BearerAuth: []
paths:
/api/generate/submit:
post:
tags:
- Audio Series
summary: xAI TTS 1
description: >-
使用五种音色之一，将 1–15,000 个字符的文本生成语音。语音设置放在 input 中。通过任务状态接口获取生成的音频；files
中的音频条目 file_type 为 audio。
operationId: submit_xai_tts_v1
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
additionalProperties: true
properties:
model:
type: string
example: xai/tts/v1
enum:
- xai/tts/v1
input:
type: object
required:
- text
additionalProperties: false
properties:
text:
type: string
minLength: 1
maxLength: 15000
description: >-
要朗读的文本，去除首尾空白后为 1 到 15,000 个字符。可使用
`[laugh]`、`[pause]`、`[sigh]`、`text` 或
`text` 控制演绎方式。
voice:
type: string
enum:
- eve
- ara
- rex
- sal
- leo
default: eve
description: 为旁白或角色选择 eve、ara、rex、sal 或 leo。默认：eve。
language_code:
type: string
enum:
- 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
default: auto
description: 选择列出的 BCP-47 语言代码，或使用 auto 自动识别语言。
output_format:
type: object
additionalProperties: false
properties:
codec:
type: string
enum:
- mp3
- wav
- pcm
- mulaw
- alaw
default: mp3
description: 音频编码：mp3、wav、pcm、mulaw 或 alaw。默认：mp3。
sample_rate:
type: integer
enum:
- 8000
- 16000
- 22050
- 24000
- 44100
- 48000
default: 24000
description: >-
采样率（Hz）：8000、16000、22050、24000、44100 或
48000。默认：24000。
bit_rate:
type: integer
nullable: true
enum:
- 32000
- 64000
- 96000
- 128000
- 192000
- null
default: 128000
description: >-
MP3 比特率（bit/s）：32000、64000、96000、128000、192000 或
null。MP3 默认：128000。wav、pcm、mulaw 和 alaw 请省略 bit_rate
或设为 null。
description: 包含 codec、sample_rate 和 MP3 bit_rate 设置的对象。
callback_url:
type: string
nullable: true
description: 提供公开的 HTTP(S) callback_url 以接收任务完成通知，建议使用 HTTPS。
description: >-
model 和 callback_url 放在根级；text、voice、language_code 和
output_format 放在 input 中。
example:
model: xai/tts/v1
input:
text: >-
Welcome to our story. [pause] Listen
closely. [laugh] Let us begin.
voice: eve
language_code: auto
output_format:
codec: mp3
sample_rate: 24000
bit_rate: 128000
responses:
'200':
description: 任务已提交
content:
application/json:
schema:
type: object
required:
- code
- data
properties:
code:
type: integer
enum:
- 200
data:
type: object
required:
- task_id
- status
- created_time
properties:
task_id:
type: string
status:
type: string
enum:
- not_started
- running
- finished
- failed
created_time:
type: string
format: date-time
example:
code: 200
data:
task_id: task-unified-example
status: running
created_time: '2026-09-10T08:00:00'
'400':
description: 请检查请求参数和账户余额。
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'401':
description: 凭证无效
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'403':
description: 拒绝访问
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'404':
description: 模型不存在或已停用
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'408':
description: 请求超时
content:
text/plain:
schema:
type: string
example: Request timeout
'422':
description: JSON 无效或请求体不是对象
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'429':
description: 已达到请求限制。请在服务指示的间隔后重试。
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'500':
description: 内部错误
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'502':
description: 任务提交失败，请重试请求。
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
'503':
description: 服务暂时不可用，请稍后重试。
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
oneOf:
- type: string
- type: object
additionalProperties: true
- type: array
items: {}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 使用 VIDGO_API_KEY。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.