> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Qwen Audio 3.1 TTS Flash 语音合成
> - 将文本转换为语音音频，单次最多 `5000` 字符
- 提供 68 个系统音色，完整列表见 [音色列表](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices)；也可以使用你自己用 [Voice Enrollment](/cn/api-manual/audio-series/qwen-audio-tts/voice-enrollment) 创建的音色（复刻或设计）
- 自定义音色默认有效期为 `6 小时`，从创建任务完成时起算；到期后合成返回 `404`（`voice_expired`），需重新调用 Voice Enrollment 创建音色
- 支持自然语言指令（`instruction`）、文本内情感与富语言标签、SSML、自定义发音（`hot_fix`）
- 只接受下方列出的参数，传入其他参数返回 `400`（`unsupported_parameter`）
- 异步处理模式，使用返回的任务ID [进行查询](/cn/api-manual/task-management/get-task-detail)
- 任务提交后不支持取消
- 生成的音频链接有效期为24小时，请尽快保存
**计费说明：**
- 按实际 token 用量计费：输入 token（与文本长度相关）和输出 token（与生成音频的时长相关）分别计价
- 提交时按文本长度预扣积分（`usage.credits_reserved`），任务完成后按实际用量结算，多退少补；任务失败全额退还
- 数字、字母、符号会被逐个念出来，生成的音频比同样长度的正文长得多，输出 token 也相应更多，实际消耗可能高于预扣
- 同一段文本，放慢语速的指令或标签（如 `[very slowly]`）会让输出 token 明显增加；`speech_rate` 调节和 SSML 插入的停顿不增加输出 token
**任务结果（`status` 为 `completed` 时）：**
| 字段 | 说明 |
|---|---|
| `results[0]` | 音频链接 |
| `result_data[0].audio_url` | 音频链接，与 `results[0]` 相同 |
| `result_data[0].format` | 音频格式 |
| `result_data[0].sample_rate` | 采样率（Hz） |
| `usage.input_tokens` / `usage.output_tokens` / `usage.total_tokens` | 本次合成的 token 用量 |
| `usage.credits_used` | 实际消耗积分 |
## OpenAPI
````yaml cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash.json POST /v1/audios/generations
openapi: 3.1.0
info:
title: Qwen Audio 3.1 TTS Flash 语音合成接口
description: 将文本转换为语音音频，提供 68 个系统音色，支持自然语言指令、情感标签、SSML 和自定义发音，按实际 token 用量计费。
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.evolink.ai
description: 生产环境
security:
- bearerAuth: []
tags:
- name: 语音合成
description: Qwen Audio 3.1 TTS Flash 语音合成相关接口
paths:
/v1/audios/generations:
post:
tags:
- 语音合成
summary: Qwen Audio 3.1 TTS Flash 语音合成
description: >-
- 将文本转换为语音音频，单次最多 `5000` 字符
- 提供 68 个系统音色，完整列表见
[音色列表](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices)；也可以使用你自己用
[Voice
Enrollment](/cn/api-manual/audio-series/qwen-audio-tts/voice-enrollment)
创建的音色（复刻或设计）
- 自定义音色默认有效期为 `6 小时`，从创建任务完成时起算；到期后合成返回 `404`（`voice_expired`），需重新调用
Voice Enrollment 创建音色
- 支持自然语言指令（`instruction`）、文本内情感与富语言标签、SSML、自定义发音（`hot_fix`）
- 只接受下方列出的参数，传入其他参数返回 `400`（`unsupported_parameter`）
- 异步处理模式，使用返回的任务ID
[进行查询](/cn/api-manual/task-management/get-task-detail)
- 任务提交后不支持取消
- 生成的音频链接有效期为24小时，请尽快保存
**计费说明：**
- 按实际 token 用量计费：输入 token（与文本长度相关）和输出 token（与生成音频的时长相关）分别计价
- 提交时按文本长度预扣积分（`usage.credits_reserved`），任务完成后按实际用量结算，多退少补；任务失败全额退还
- 数字、字母、符号会被逐个念出来，生成的音频比同样长度的正文长得多，输出 token 也相应更多，实际消耗可能高于预扣
- 同一段文本，放慢语速的指令或标签（如 `[very slowly]`）会让输出 token 明显增加；`speech_rate` 调节和
SSML 插入的停顿不增加输出 token
**任务结果（`status` 为 `completed` 时）：**
| 字段 | 说明 |
|---|---|
| `results[0]` | 音频链接 |
| `result_data[0].audio_url` | 音频链接，与 `results[0]` 相同 |
| `result_data[0].format` | 音频格式 |
| `result_data[0].sample_rate` | 采样率（Hz） |
| `usage.input_tokens` / `usage.output_tokens` / `usage.total_tokens` |
本次合成的 token 用量 |
| `usage.credits_used` | 实际消耗积分 |
operationId: createQwenAudio31TtsFlash
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QwenAudioTtsRequest'
examples:
basic:
summary: 最简调用（默认音色）
value:
model: qwen-audio-3.1-tts-flash
prompt: 我家的后面有一个很大的花园。
aliases:
summary: 使用文本与格式别名
value:
model: qwen-audio-3.1-tts-flash
input: 我家的后面有一个很大的花园。
format: mp3
with_voice:
summary: 指定音色与输出格式
value:
model: qwen-audio-3.1-tts-flash
prompt: 各位听众朋友，大家好，欢迎收听晚间新闻。
voice: xuyanchu_v3.1
response_format: wav
sample_rate: 48000
expressive:
summary: 指令与情感标签
value:
model: qwen-audio-3.1-tts-flash
prompt: '[excited]今天的天气真不错！[laughing]我们一起出去玩吧！'
voice: longanhuan_v3.1
instruction: 用欢快、热情的语气说
english:
summary: 英文音色
value:
model: qwen-audio-3.1-tts-flash
prompt: Hello, this is 110. Please leave a message after the tone.
voice: Emily_v3.1
language: en
speech_rate: 0.9
ssml:
summary: SSML 停顿
value:
model: qwen-audio-3.1-tts-flash
prompt: 欢迎收听今天的节目。我们马上开始。
enable_ssml: true
full_params:
summary: 完整参数
value:
model: qwen-audio-3.1-tts-flash
prompt: 今天的天气真不错，适合出去走走。
voice: yuxiaoyun_v3.1
response_format: mp3
sample_rate: 24000
volume: 60
speech_rate: 1.1
pitch: 1
instruction: 语气轻松自然，像在和朋友聊天
language: zh
enable_ssml: false
hot_fix:
pronunciation:
- 天气: tian1 qi4
replace:
- 走走: 走一走
enable_aigc_tag: false
callback_url: https://your-domain.com/webhooks/tts-completed
responses:
'200':
description: 语音合成任务创建成功
content:
application/json:
schema:
$ref: '#/components/schemas/QwenAudioTtsResponse'
'400':
description: 请求参数错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_prompt:
summary: 缺少 prompt
value:
error:
code: missing_prompt
message: prompt is required for qwen-audio-3.1-tts-flash
type: invalid_request_error
prompt_too_long:
summary: prompt 超过 5000 字符
value:
error:
code: prompt_too_long
message: prompt must be at most 5000 characters, got 5210
type: invalid_request_error
prompt_too_long_after_replace:
summary: hot_fix.replace 替换后超过 5000 字符
value:
error:
code: prompt_too_long
message: >-
prompt must be at most 5000 characters after
hot_fix.replace is applied, got 5120
type: invalid_request_error
hot_fix_too_many_entries:
summary: hot_fix 条目超过 200 条
value:
error:
code: invalid_parameter
message: >-
hot_fix may contain at most 200 entries in total, got
201
type: invalid_request_error
invalid_voice:
summary: 音色不在支持列表中
value:
error:
code: invalid_voice
message: >-
voice "longanhuan" is not available for
qwen-audio-3.1-tts-flash; use a system voice from the
voice list or a voice you created with voice-enrollment
type: invalid_request_error
instruction_too_long:
summary: instruction 超过 100 计费字符
value:
error:
code: instruction_too_long
message: >-
instruction must be at most 100 billing characters (CJK
characters count as 2), got 124
type: invalid_request_error
wrong_parameter_name:
summary: 参数名写错（instructions）
value:
error:
code: unsupported_parameter
message: instructions is not supported; use "instruction"
type: invalid_request_error
unsupported_parameter:
summary: 传入了不支持的参数
value:
error:
code: unsupported_parameter
message: seed is not supported for qwen-audio-3.1-tts-flash
type: invalid_request_error
opus_sample_rate:
summary: opus 格式使用了不支持的采样率
value:
error:
code: invalid_parameter
message: >-
sample_rate 44100 is not supported with
response_format=opus; use one of: 8000, 12000, 16000,
24000, 48000
type: invalid_request_error
'401':
description: 未认证、Token无效或过期
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: unauthorized
message: Invalid or expired token
type: authentication_error
'402':
description: 配额不足、需要充值
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: insufficient_quota
message: Insufficient quota. Please top up your account.
type: insufficient_quota
'403':
description: 无权限访问
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: model_access_denied
message: >-
Token does not have access to model:
qwen-audio-3.1-tts-flash
type: invalid_request_error
'404':
description: 音色不存在或已过期
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
voice_not_found:
summary: 音色不存在或不属于当前账号
value:
error:
code: voice_not_found
message: >-
voice
"qwen-audio-3.1-tts-flash-myvoice-5996beec833d41f4982158347ba97fae"
not found
type: invalid_request_error
voice_expired:
summary: 自定义音色已过期，需重新创建
value:
error:
code: voice_expired
message: >-
voice
"qwen-audio-3.1-tts-flash-myvoice-5996beec833d41f4982158347ba97fae"
has expired; create a new one with voice-enrollment
type: invalid_request_error
'429':
description: 请求频率超限
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: rate_limit_exceeded
message: Too many requests, please try again later
type: rate_limit_error
'500':
description: 服务器内部错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: internal_error
message: Internal server error
type: api_error
components:
schemas:
QwenAudioTtsRequest:
type: object
required:
- model
description: >-
`prompt` 和 `input` 至少提供一个非空文本；同时提供时内容必须一致。`response_format` 和 `format`
同时提供时取值必须一致。
anyOf:
- required:
- prompt
properties:
prompt:
pattern: \S
- required:
- input
properties:
input:
pattern: \S
properties:
model:
type: string
description: 模型名称
enum:
- qwen-audio-3.1-tts-flash
default: qwen-audio-3.1-tts-flash
example: qwen-audio-3.1-tts-flash
prompt:
type: string
description: >-
待合成的文本
**约束：**
- 最多 `5000` 字符
- 长文本请保留标点：没有句读的连续长段会被上游截断到约 `1500` 个输出 token（约 120
秒音频），任务仍报成功并按实际生成的 token 计费，网关无法检测这种截断
- 也可用 `input` 传入，至少提供一个非空文本；建议只传一个，同时传入且内容不同时返回
`400`（`parameter_conflict`）
- 文本须在所选音色支持的语言范围内，否则可能出现发音错误
**情感与富语言标签：** 可直接在文本中嵌入标签，无需额外参数；标签文字计入计费字符
- **控制类标签**：设定其后文本的情感或风格，直到遇到下一个控制类标签。`[sad]` 悲伤、`[amazed]`
惊叹、`[deep and loud shouting]` 深沉大声呐喊、`[trembling]` 颤抖、`[angry]`
愤怒、`[excited]` 兴奋、`[sarcastic]` 讽刺、`[curious]` 好奇、`[like dracula]`
低沉阴森、`[bored]` 无聊、`[tired]` 疲惫、`[scornful]` 轻蔑、`[shouting]`
大喊、`[asmr]` ASMR 轻柔耳语、`[panicked]` 恐慌、`[mischievously]`
调皮、`[empathetic]` 共情、`[whispers]` 耳语、`[reluctantly]` 不情愿、`[crying]`
哭泣、`[serious]` 严肃、`[very slowly]` 非常缓慢、`[very fast]` 非常快速
- **富语言类标签**：在当前位置插入一段拟声效果，不影响前后文本的情感。`[gasp]` 倒吸一口气、`[sighing]`
叹息、`[clears throat]` 清嗓、`[giggles]` 咯咯笑、`[laughing]` 大笑、`[cough]`
咳嗽、`[snorts]` 哼声
**示例：** `[excited]今天的天气真不错！[laughing]我们一起出去玩吧！`
`enable_ssml` 为 `true` 时，本字段按 SSML 解析
maxLength: 5000
example: 我家的后面有一个很大的花园。
input:
type: string
description: |-
`prompt` 的别名，文本长度和使用规则与 `prompt` 相同
- `prompt` 和 `input` 至少提供一个非空文本
- 同时提供时内容必须一致，否则返回 `400`（`parameter_conflict`）
maxLength: 5000
example: 我家的后面有一个很大的花园。
voice:
type: string
description: >-
音色名称，区分大小写
- 共 68 个系统音色，名称、性别、适用场景见
[音色列表](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices)
- 不传时默认使用 `longanhuan_v3.1`
- 也可以传你自己用 [Voice
Enrollment](/cn/api-manual/audio-series/qwen-audio-tts/voice-enrollment)
创建的音色：复刻的形如 `qwen-audio-3.1-tts-flash-{前缀}-{32 位标识}`，设计的形如
`qwen-audio-3.1-tts-flash-vd-{前缀}-{32 位标识}`。只有创建它的账号能用；别的模型创建的音色（如
`qwen-voice-design` 的 `qwen-tts-vd-…`）不能用，返回
`400`（`invalid_voice`）；不存在或不属于你的音色返回 `404`（`voice_not_found`）
- 自定义音色默认有效期为 `6 小时`，从创建任务完成时起算；到期后合成返回 `404`（`voice_expired`），需重新调用
Voice Enrollment 创建音色
default: longanhuan_v3.1
example: longanhuan_v3.1
response_format:
type: string
description: |-
输出音频格式，支持 `mp3`、`wav`、`opus`，默认 `mp3`
- `opus` 为 Ogg Opus 封装
- 也可用 `format` 传入；建议只传一个，同时传入且取值不同时返回 `400`（`parameter_conflict`）
enum:
- mp3
- wav
- opus
default: mp3
example: mp3
format:
type: string
description: |-
`response_format` 的别名，支持 `mp3`、`wav`、`opus`
- 两个字段都未提供时默认使用 `mp3`
- 同时提供时取值必须一致，否则返回 `400`（`parameter_conflict`）
enum:
- mp3
- wav
- opus
example: mp3
sample_rate:
type:
- integer
- 'null'
description: |-
输出采样率（Hz）
- `response_format` 为 `opus` 时不支持 `22050` 和 `44100`
- 不传或传 `null` 时使用默认值；传 `0` 或列表以外的值返回 `400`
enum:
- 8000
- 12000
- 16000
- 22050
- 24000
- 44100
- 48000
- null
default: 24000
example: 24000
volume:
type: integer
description: 音量，取值范围 `0` ~ `100`
minimum: 0
maximum: 100
default: 50
example: 50
speech_rate:
type: number
description: |-
语速倍数
- `1.0`：正常语速（默认）
- `2.0`：两倍速；`0.5`：半速
取值范围 `0.5` ~ `2.0`。调节语速不改变输出 token 数
minimum: 0.5
maximum: 2
default: 1
example: 1
pitch:
type: number
description: >-
音调倍数
- `1.0`：默认音调
- 大于 `1.0` 声音更高，小于 `1.0` 声音更低
取值范围 `0.5` ~ `2.0`
**注意：调节音调会同时改变语速和音频时长**
- 音调越高语速越快、时长越短，音调越低语速越慢、时长越长，时长大约按音调值的平方反比变化
- 以一句 `1.0` 时约 2.8 秒的话为例：`0.8` 约 4.3 秒，`1.2` 约 2.1 秒，`0.5` 约 10.9
秒，`2.0` 约 0.7 秒
- 建议在 `0.8` ~ `1.2` 之间微调；接近 `0.5` 或 `2.0` 时语音会明显过慢或过快
- 同时传了不等于 `1.0` 的 `speech_rate` 时，`pitch` 不生效；两者不能叠加使用
- 调节音调不改变输出 token 数
minimum: 0.5
maximum: 2
default: 1
example: 1
instruction:
type: string
description: >-
自然语言指令，用于控制情感、语气、角色、方言等表达方式
**约束：**
- 不超过 `100` 计费字符：汉字（包括日文汉字、韩文汉字）按 2 计，其他字符按 1 计（假名、韩文字母均按 1 计；约 50
个汉字或 100 个英文字符），超出返回 `400`
**示例：**
- `用欢快、热情的语气说`
- `请用上海话表达`（多语种与方言音色）
- `Speak slowly in a calm and gentle tone`
指令本身不计入输入 token，但会影响生成音频的时长，从而影响输出 token
> 参数名为 `instruction`（单数），传 `instructions` 会返回 `400`
example: 用欢快、热情的语气说
language:
type: string
description: |-
目标语种提示，用于改善数字、缩写、符号的读法和小语种的合成效果
例如英文句子 `hello, this is 110` 传 `zh` 时，`110` 读作「幺幺零」
| 值 | 语种 | 值 | 语种 |
|---|---|---|---|
| `zh` | 中文 | `th` | 泰语 |
| `en` | 英语 | `id` | 印尼语 |
| `fr` | 法语 | `vi` | 越南语 |
| `de` | 德语 | `es` | 西班牙语 |
| `ja` | 日语 | `it` | 意大利语 |
| `ko` | 韩语 | `ms` | 马来语 |
| `ru` | 俄语 | `fil` | 菲律宾语 |
| `pt` | 葡萄牙语 | `ar` | 阿拉伯语 |
不传时由模型自动判断；本参数不会翻译文本
enum:
- zh
- en
- fr
- de
- ja
- ko
- ru
- pt
- th
- id
- vi
- es
- it
- ms
- fil
- ar
example: zh
enable_ssml:
type: boolean
description: |-
是否按 SSML 解析 `prompt`
开启后可使用 SSML 标签，例如用 `` 插入停顿：
`欢迎收听今天的节目。我们马上开始。`
SSML 插入的停顿不计入输出 token
default: false
example: false
hot_fix:
type: object
description: >-
自定义发音与文本替换，用于纠正多音字、专有名词等读音
- `pronunciation`：为指定词语标注拼音（音节间用空格分隔，声调用数字标注，如 `tian1 qi4`），纠正默认读音
- `replace`：合成前把指定词语替换为目标文本，按替换后的文本合成和计费；替换后的文本同样不能超过 `5000` 字符，超出返回
`400`（`prompt_too_long`）
两类词条合计最多 `200` 条（按对象中的键值对计数），超过返回 `400`（`invalid_parameter`）
两项至少传一项，每项为非空数组，数组元素为 `{"词语": "值"}` 形式的对象
**示例：**
```json
{
"pronunciation": [{"天气": "tian1 qi4"}],
"replace": [{"今天": "金天"}]
}
```
properties:
pronunciation:
type: array
description: '自定义发音列表，每项为 `{"词语": "拼音"}`'
items:
type: object
additionalProperties:
type: string
example:
- 天气: tian1 qi4
replace:
type: array
description: '文本替换列表，每项为 `{"原词": "替换文本"}`'
items:
type: object
additionalProperties:
type: string
example:
- 今天: 金天
enable_aigc_tag:
type: boolean
description: 是否在生成的音频中嵌入 AIGC 隐性标识（`wav` / `mp3` / `opus` 格式生效）
default: false
example: false
callback_url:
type: string
description: |-
任务完成后的HTTPS回调地址
**回调时机：**
- 任务完成（completed）或失败（failed）时触发；本模型不支持取消
- 在计费确认完成后发送
**安全限制：**
- 仅支持HTTPS协议
- 禁止回调到内网IP地址（127.0.0.1、10.x.x.x、172.16-31.x.x、192.168.x.x等）
- URL长度不超过`2048`字符
**回调机制：**
- 超时时间：`10`秒
- 失败后最多重试`3`次（会分别在失败的`1`秒/`2`秒/`4`秒后进行重试）
- 回调响应体格式与任务查询接口返回的格式一致
- 回调地址若返回2xx状态码视为成功，其他状态码会触发重试
format: uri
example: https://your-domain.com/webhooks/tts-completed
QwenAudioTtsResponse:
type: object
properties:
created:
type: integer
description: 任务创建时间戳
example: 1790000000
id:
type: string
description: 任务ID
example: task-unified-1790000000-abcd1234
model:
type: string
description: 实际使用的模型名称
example: qwen-audio-3.1-tts-flash
object:
type: string
enum:
- audio.generation.task
description: 任务的具体类型
progress:
type: integer
description: 任务进度百分比 (0-100)
minimum: 0
maximum: 100
example: 0
status:
type: string
description: 任务状态
enum:
- pending
- processing
- completed
- failed
example: pending
task_info:
$ref: '#/components/schemas/AudioTaskInfo'
description: 音频任务详细信息
type:
type: string
enum:
- audio
description: 任务的输出类型
example: audio
usage:
$ref: '#/components/schemas/AudioUsage'
description: 使用量和计费信息
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: 错误代码标识符
message:
type: string
description: 错误描述信息
type:
type: string
description: 错误类型
AudioTaskInfo:
type: object
properties:
can_cancel:
type: boolean
description: 任务是否可以取消（本模型不支持取消）
example: false
estimated_time:
type: integer
description: 预估完成时间（秒），随文本长度增加，最长约 `90` 秒
minimum: 0
example: 3
audio_type:
type: string
description: 音频任务类型
example: tts
AudioUsage:
type: object
description: 使用量信息
properties:
credits_reserved:
type: number
description: 预扣积分数（按文本长度预估，任务完成后按实际 token 用量结算，多退少补）
minimum: 0
example: 0.0144
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: |-
##所有接口均需要使用Bearer Token进行认证##
**获取 API Key：**
访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key
**使用时在请求头中添加：**
```
Authorization: Bearer YOUR_API_KEY
```
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.