> ## 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.
# ElevenLabs V3 TTS
> 使用 ElevenLabs V3 将文本转为语音，可选择音色、控制语言，并可返回时间戳，适用于旁白和对话。
> [!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)接口获取结果。
使用 ElevenLabs V3 将文本转为语音，可选择音色、控制语言，并可返回时间戳，适用于旁白和对话。
## 模型
* **elevenlabs/tts/eleven-v3** - 将文本转换为语音。
## 功能
* 将文本转换为语音。
* 可在生成音频的同时请求时间戳。
* 使用 `voice` 选择音色，使用 `language_code` 指定朗读语言。
## 高级参数
在请求根级设置 `model` 和可选的 `callback_url`。所有工作流程参数（包括输出选项）都放在 `input` 中。
### 文本
* `text`：必填。要朗读的文本。长度：**1-5,000 个字符**。
* 检查字符上限前会先去除首尾空白。
### 音色
* `voice`：可选。选择音色。字符串。默认：`Rachel`。
* 可选值：`Aria`、`Roger`、`Sarah`、`Laura`、`Charlie`、`George`、`Callum`、`River`、`Liam`、`Charlotte`、`Alice`、`Matilda`、`Will`、`Jessica`、`Eric`、`Chris`、`Brian`、`Daniel`、`Lily`、`Bill`、`Rachel`。
### 稳定性
* `stability`：可选。控制音色稳定性。数值 `0` 到 `1`。默认：`0.5`。
### 时间戳
* `timestamps`：可选。在返回音频的同时请求时间戳信息。使用 `true` 或 `false`。默认：`false`。
### 语言代码
* `language_code`：可选。ISO 639-1 语言代码，例如英语为 `en`，中文为 `zh`。
### 文本规范化
* `apply_text_normalization`：可选。选择文本规范化行为。可选值：`auto`、`on`、`off`。默认：`auto`。
## 输出文件
* 读取返回的 `files` 数组中的每一项。
* 生成的音频 `file_type` 为 `"audio"`。
* 返回的 `timestamps.json` 是单独的一项，`file_type` 为 `"other"`。如有可选的文件元数据，请一并保留。
## 示例
每个示例都包含请求、对应的已完成任务响应和生成的音频。将请求提交到 `POST https://api.vidgo.ai/api/generate/submit`，然后使用提交返回的任务 ID 查询 `GET https://api.vidgo.ai/api/generate/status/{task_id}`。
> [accordion] 阁楼上的星星
>
> ```json Request theme={null}
> {
> "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 Completed task response theme={null}
> {
> "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
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/01/speech.mp3)
> [accordion] 我的第一个饺子
>
> ```json Request theme={null}
> {
> "model": "elevenlabs/tts/eleven-v3",
> "input": {
> "text": "[sighs] 我练了一个下午，面团还是歪歪扭扭的。奶奶看了一眼，说：别急，手放轻一点。[curious] 这样吗？先对折，再慢慢捏紧……[laughs] 真的站住了！虽然像只胖企鹅，但这是我第一次包好饺子。原来，有些本事不是听懂的，是一起做着学会的。",
> "voice": "Rachel",
> "language_code": "zh",
> "stability": 0.5,
> "timestamps": false,
> "apply_text_normalization": "auto"
> }
> }
> ```
>
> ```json Completed task response theme={null}
> {
> "code": 200,
> "data": {
> "task_id": "VLXQ5DI7PNWFRJQ4",
> "status": "finished",
> "files": [
> {
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/02/speech.mp3",
> "file_type": "audio",
> "file_name": "speech.mp3"
> }
> ],
> "created_time": "2026-09-27T10:46:38",
> "error_message": null,
> "progress": 100
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/02/speech.mp3)
> [accordion] 声音的性格
>
> ```json Request theme={null}
> {
> "model": "elevenlabs/tts/eleven-v3",
> "input": {
> "text": "[curious] Why does a violin sound different from a flute when both play the same note? Their fundamental frequency can match, but the overtones do not. [excited] Those extra vibrations give each instrument its own sound. At 440 Hz, the pitch is A; the pattern above it is what makes the voice of the instrument recognizable.",
> "voice": "George",
> "language_code": "en",
> "stability": 0.5,
> "timestamps": true,
> "apply_text_normalization": "on"
> }
> }
> ```
>
> ```json Completed task response theme={null}
> {
> "code": 200,
> "data": {
> "task_id": "0E09515629QS87GR",
> "status": "finished",
> "files": [
> {
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/03/speech.mp3",
> "file_type": "audio",
> "file_name": "speech.mp3"
> },
> {
> "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/03/timestamps.json",
> "file_type": "other",
> "file_name": "timestamps.json"
> }
> ],
> "created_time": "2026-09-27T10:47:13",
> "error_message": null,
> "progress": 100
> }
> }
> ```
>
>
>
> [下载音频](https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/03/speech.mp3)
>
> [下载 timestamps.json](https://cdn.vidgo.ai/apis/models/elevenlabs/tts/eleven-v3/v1/03/timestamps.json)
## OpenAPI
````yaml zh/api-manual/music-series/elevenlabs-tts-eleven-v3.json POST /api/generate/submit
openapi: 3.0.0
info:
title: Vidgo API - ElevenLabs V3 TTS
description: 使用 ElevenLabs V3 将文本转为语音，可选择音色、控制语言，并可返回时间戳，适用于旁白和对话。
version: 1.0.0
servers:
- url: https://api.vidgo.ai
security:
- BearerAuth: []
paths:
/api/generate/submit:
post:
tags:
- Audio Series
summary: ElevenLabs V3 TTS
description: 将文本转换为语音，可设置音色、稳定性、语言和文本规范化。提交请求后，使用 task_id 获取音频，以及 files 中返回的时间戳附件。
operationId: submit_elevenlabs_tts_eleven_v3
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
additionalProperties: true
properties:
model:
type: string
example: elevenlabs/tts/eleven-v3
enum:
- elevenlabs/tts/eleven-v3
input:
type: object
required:
- text
additionalProperties: false
properties:
text:
type: string
minLength: 1
maxLength: 5000
description: 要朗读的文本，去除首尾空白后为 1–5,000 个字符。
voice:
type: string
default: Rachel
description: 用于生成语音的音色名称，从列出的音色中选择一个。
enum:
- Aria
- Roger
- Sarah
- Laura
- Charlie
- George
- Callum
- River
- Liam
- Charlotte
- Alice
- Matilda
- Will
- Jessica
- Eric
- Chris
- Brian
- Daniel
- Lily
- Bill
- Rachel
stability:
type: number
minimum: 0
maximum: 1
default: 0.5
description: 音色稳定性，取值 0 到 1。
timestamps:
type: boolean
default: false
description: >-
设为 true 时请求时间戳。返回的 timestamps.json 是 files
中单独的一项，file_type 为 other。
language_code:
type: string
description: 可选的 ISO 639-1 语言代码，用于指定朗读语言，例如 en 或 zh。
apply_text_normalization:
type: string
enum:
- auto
- 'on'
- 'off'
default: auto
description: 选择 auto、on 或 off，控制生成语音前的文本规范化。
callback_url:
type: string
nullable: true
description: 可选的公开 HTTP(S) URL，用于接收任务完成或失败的通知。
description: 在请求根级设置 model 和可选的 callback_url，语音生成参数放在 input 中。
examples:
basic:
summary: 阁楼上的星星
value:
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
eleven-v3-02:
summary: 我的第一个饺子
value:
model: elevenlabs/tts/eleven-v3
input:
text: >-
[sighs] 我练了一个下午，面团还是歪歪扭扭的。奶奶看了一眼，说：别急，手放轻一点。[curious]
这样吗？先对折，再慢慢捏紧……[laughs]
真的站住了！虽然像只胖企鹅，但这是我第一次包好饺子。原来，有些本事不是听懂的，是一起做着学会的。
voice: Rachel
language_code: zh
stability: 0.5
timestamps: false
apply_text_normalization: auto
eleven-v3-03:
summary: 声音的性格
value:
model: elevenlabs/tts/eleven-v3
input:
text: >-
[curious] Why does a violin sound different from a flute
when both play the same note? Their fundamental frequency
can match, but the overtones do not. [excited] Those extra
vibrations give each instrument its own sound. At 440 Hz,
the pitch is A; the pattern above it is what makes the
voice of the instrument recognizable.
voice: George
language_code: en
stability: 0.5
timestamps: true
apply_text_normalization: 'on'
callback:
summary: 接收完成回调
value:
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
callback_url: https://your-domain.com/callback
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: LPV36KJQ0Y2SYT21
status: running
created_time: '2026-09-27T10:45:57'
'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: 超出速率限制或 API Key 积分限额
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.