> ## 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 Speech Synthesis
> - Convert text to speech, up to `5000` characters per request
- Choose from 68 system voices; see the [voice list](/en/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices). You can also use a voice you created with [Voice Enrollment](/en/api-manual/audio-series/qwen-audio-tts/voice-enrollment), through cloning or design
- Custom voices expire by default `6 hours` after the creation task completes; synthesis after expiry returns `404` (`voice_expired`). Create a new voice with Voice Enrollment
- Supports natural-language instructions (`instruction`), inline emotion and paralinguistic tags, SSML, and custom pronunciation (`hot_fix`)
- Only the parameters listed below are accepted; other parameters return `400` (`unsupported_parameter`)
- Asynchronous processing; use the returned task ID to [query the result](/en/api-manual/task-management/get-task-detail)
- Tasks cannot be canceled after submission
- Generated audio links are valid for 24 hours; save them promptly
**Billing:**
- Billed by actual token usage: input tokens (related to text length) and output tokens (related to generated audio duration) are priced separately
- Credits are reserved at submission based on text length (`usage.credits_reserved`). On completion, billing is settled against actual usage: excess is refunded and any shortfall is charged. Failed tasks receive a full refund
- Numbers, letters, and symbols may be read individually, producing much longer audio and more output tokens than ordinary prose of the same length; actual usage may exceed the reservation
- For the same text, instructions or tags that slow delivery (such as `[very slowly]`) can substantially increase output tokens. Adjusting `speech_rate` and inserting SSML pauses do not increase output tokens
**Task result (when `status` is `completed`):**
| Field | Description |
|---|---|
| `results[0]` | Audio URL |
| `result_data[0].audio_url` | Audio URL, identical to `results[0]` |
| `result_data[0].format` | Audio format |
| `result_data[0].sample_rate` | Sample rate (Hz) |
| `usage.input_tokens` / `usage.output_tokens` / `usage.total_tokens` | Token usage for this synthesis |
| `usage.credits_used` | Actual credits used |
## OpenAPI
````yaml en/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 Speech Synthesis API
description: >-
Convert text to speech with 68 system voices, natural-language instructions,
emotion tags, SSML, and custom pronunciation. Billing is based on actual
token usage.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.evolink.ai
description: Production environment
security:
- bearerAuth: []
tags:
- name: Speech Synthesis
description: Qwen Audio 3.1 TTS Flash speech synthesis endpoints
paths:
/v1/audios/generations:
post:
tags:
- Speech Synthesis
summary: Qwen Audio 3.1 TTS Flash Speech Synthesis
description: >-
- Convert text to speech, up to `5000` characters per request
- Choose from 68 system voices; see the [voice
list](/en/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices).
You can also use a voice you created with [Voice
Enrollment](/en/api-manual/audio-series/qwen-audio-tts/voice-enrollment),
through cloning or design
- Custom voices expire by default `6 hours` after the creation task
completes; synthesis after expiry returns `404` (`voice_expired`).
Create a new voice with Voice Enrollment
- Supports natural-language instructions (`instruction`), inline emotion
and paralinguistic tags, SSML, and custom pronunciation (`hot_fix`)
- Only the parameters listed below are accepted; other parameters return
`400` (`unsupported_parameter`)
- Asynchronous processing; use the returned task ID to [query the
result](/en/api-manual/task-management/get-task-detail)
- Tasks cannot be canceled after submission
- Generated audio links are valid for 24 hours; save them promptly
**Billing:**
- Billed by actual token usage: input tokens (related to text length)
and output tokens (related to generated audio duration) are priced
separately
- Credits are reserved at submission based on text length
(`usage.credits_reserved`). On completion, billing is settled against
actual usage: excess is refunded and any shortfall is charged. Failed
tasks receive a full refund
- Numbers, letters, and symbols may be read individually, producing much
longer audio and more output tokens than ordinary prose of the same
length; actual usage may exceed the reservation
- For the same text, instructions or tags that slow delivery (such as
`[very slowly]`) can substantially increase output tokens. Adjusting
`speech_rate` and inserting SSML pauses do not increase output tokens
**Task result (when `status` is `completed`):**
| Field | Description |
|---|---|
| `results[0]` | Audio URL |
| `result_data[0].audio_url` | Audio URL, identical to `results[0]` |
| `result_data[0].format` | Audio format |
| `result_data[0].sample_rate` | Sample rate (Hz) |
| `usage.input_tokens` / `usage.output_tokens` / `usage.total_tokens` |
Token usage for this synthesis |
| `usage.credits_used` | Actual credits used |
operationId: createQwenAudio31TtsFlash
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QwenAudioTtsRequest'
examples:
basic:
summary: Minimal request (default voice)
value:
model: qwen-audio-3.1-tts-flash
prompt: 我家的后面有一个很大的花园。
aliases:
summary: Text and format aliases
value:
model: qwen-audio-3.1-tts-flash
input: 我家的后面有一个很大的花园。
format: mp3
with_voice:
summary: Select a voice and output format
value:
model: qwen-audio-3.1-tts-flash
prompt: 各位听众朋友，大家好，欢迎收听晚间新闻。
voice: xuyanchu_v3.1
response_format: wav
sample_rate: 48000
expressive:
summary: Instructions and emotion tags
value:
model: qwen-audio-3.1-tts-flash
prompt: '[excited]今天的天气真不错！[laughing]我们一起出去玩吧！'
voice: longanhuan_v3.1
instruction: 用欢快、热情的语气说
english:
summary: English voice
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 pauses
value:
model: qwen-audio-3.1-tts-flash
prompt: 欢迎收听今天的节目。我们马上开始。
enable_ssml: true
full_params:
summary: Full parameters
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: Speech synthesis task created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QwenAudioTtsResponse'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_prompt:
summary: Missing 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 exceeds 5000 characters
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: Text exceeds 5000 characters after hot_fix.replace
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 exceeds 200 entries
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: Voice is not in the supported list
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 exceeds 100 billing characters
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: Incorrect parameter name (instructions)
value:
error:
code: unsupported_parameter
message: instructions is not supported; use "instruction"
type: invalid_request_error
unsupported_parameter:
summary: Unsupported parameter supplied
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: Unsupported sample rate for 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: Unauthenticated, invalid or expired token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: unauthorized
message: Invalid or expired token
type: authentication_error
'402':
description: Insufficient quota; top up required
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: Access denied
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: Voice does not exist or has expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
voice_not_found:
summary: Voice does not exist or belongs to another account
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: Custom voice has expired; create a new one
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: Rate limit exceeded
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: Internal server error
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: >-
Provide at least one non-empty text field, `prompt` or `input`; if both
are supplied, their contents must match. If both `response_format` and
`format` are supplied, their values must match.
anyOf:
- required:
- prompt
properties:
prompt:
pattern: \S
- required:
- input
properties:
input:
pattern: \S
properties:
model:
type: string
description: Model name
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: >-
Text to synthesize
**Constraints:**
- Maximum `5000` characters
- Keep punctuation in long text: long continuous passages without
sentence breaks may be truncated upstream at about `1500` output
tokens (about 120 seconds of audio). The task still reports success
and is billed for the tokens actually generated; the gateway cannot
detect this truncation
- You can also use `input`. At least one non-empty text field is
required; supplying just one is recommended. Different contents in
both fields return `400` (`parameter_conflict`)
- Text must be in a language supported by the selected voice;
otherwise pronunciation may be incorrect
**Emotion and paralinguistic tags:** Embed tags directly in the text
without extra parameters; tag text counts toward billing characters
- **Control tags**: Set the emotion or style of the following text
until the next control tag. `[sad]` sad, `[amazed]` amazed, `[deep
and loud shouting]` deep, loud shouting, `[trembling]` trembling,
`[angry]` angry, `[excited]` excited, `[sarcastic]` sarcastic,
`[curious]` curious, `[like dracula]` low and eerie, `[bored]`
bored, `[tired]` tired, `[scornful]` scornful, `[shouting]`
shouting, `[asmr]` soft ASMR whispers, `[panicked]` panicked,
`[mischievously]` mischievous, `[empathetic]` empathetic,
`[whispers]` whispering, `[reluctantly]` reluctant, `[crying]`
crying, `[serious]` serious, `[very slowly]` very slowly, `[very
fast]` very fast
- **Paralinguistic tags**: Insert a vocal effect at this position
without changing the emotion of the surrounding text. `[gasp]` gasp,
`[sighing]` sigh, `[clears throat]` clear the throat, `[giggles]`
giggle, `[laughing]` laugh, `[cough]` cough, `[snorts]` snort
**Example:** `[excited]今天的天气真不错！[laughing]我们一起出去玩吧！`
When `enable_ssml` is `true`, this field is parsed as SSML
maxLength: 5000
example: 我家的后面有一个很大的花园。
input:
type: string
description: >-
Alias for `prompt`, with the same length limits and usage rules
- Provide at least one non-empty text field, `prompt` or `input`
- If both are supplied, their contents must match; otherwise `400`
(`parameter_conflict`) is returned
maxLength: 5000
example: 我家的后面有一个很大的花园。
voice:
type: string
description: >-
Voice name, case-sensitive
- 68 system voices; see the [voice
list](/en/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash-voices)
for names, gender, and use cases
- Defaults to `longanhuan_v3.1` if omitted
- You can also supply a voice you created with [Voice
Enrollment](/en/api-manual/audio-series/qwen-audio-tts/voice-enrollment):
cloned voices follow
`qwen-audio-3.1-tts-flash-{prefix}-{32-character-id}`, and designed
voices follow
`qwen-audio-3.1-tts-flash-vd-{prefix}-{32-character-id}`. Only the
account that created the voice can use it. Voices from other models,
such as `qwen-tts-vd-…` from `qwen-voice-design`, return `400`
(`invalid_voice`). Missing voices or voices owned by another account
return `404` (`voice_not_found`)
- Custom voices expire by default `6 hours` after the creation task
completes; synthesis after expiry returns `404` (`voice_expired`).
Create a new voice with Voice Enrollment
default: longanhuan_v3.1
example: longanhuan_v3.1
response_format:
type: string
description: >-
Output audio format: `mp3`, `wav`, or `opus`; defaults to `mp3`
- `opus` uses an Ogg Opus container
- You can also use `format`. Supplying just one field is
recommended; conflicting values return `400` (`parameter_conflict`)
enum:
- mp3
- wav
- opus
default: mp3
example: mp3
format:
type: string
description: >-
Alias for `response_format`; supports `mp3`, `wav`, and `opus`
- Defaults to `mp3` when neither field is supplied
- If both fields are supplied, their values must match; otherwise
`400` (`parameter_conflict`) is returned
enum:
- mp3
- wav
- opus
example: mp3
sample_rate:
type:
- integer
- 'null'
description: >-
Output sample rate (Hz)
- `22050` and `44100` are not supported when `response_format` is
`opus`
- Omitted or `null` uses the default; `0` or a value outside the
list returns `400`
enum:
- 8000
- 12000
- 16000
- 22050
- 24000
- 44100
- 48000
- null
default: 24000
example: 24000
volume:
type: integer
description: Volume, from `0` to `100`
minimum: 0
maximum: 100
default: 50
example: 50
speech_rate:
type: number
description: >-
Speech rate multiplier
- `1.0`: normal speed (default)
- `2.0`: double speed; `0.5`: half speed
Range: `0.5` to `2.0`. Adjusting speech rate does not change output
token count
minimum: 0.5
maximum: 2
default: 1
example: 1
pitch:
type: number
description: >-
Pitch multiplier
- `1.0`: default pitch
- Above `1.0` raises pitch; below `1.0` lowers it
Range: `0.5` to `2.0`
**Changing pitch also changes speech rate and audio duration**
- Higher pitch speeds up speech and shortens audio; lower pitch
slows it down and lengthens audio. Duration varies approximately
inversely with the square of the pitch value
- For a sentence lasting about 2.8 seconds at `1.0`: `0.8` is about
4.3 seconds, `1.2` about 2.1 seconds, `0.5` about 10.9 seconds, and
`2.0` about 0.7 seconds
- Small adjustments between `0.8` and `1.2` are recommended; values
near `0.5` or `2.0` make speech noticeably too slow or too fast
- If `speech_rate` is also supplied with a value other than `1.0`,
`pitch` has no effect; the two cannot be combined
- Adjusting pitch does not change output token count
minimum: 0.5
maximum: 2
default: 1
example: 1
instruction:
type: string
description: >-
Natural-language instructions to control emotion, tone, character,
dialect, and other delivery choices
**Constraints:**
- Maximum `100` billing characters: Han characters (including
Japanese kanji and Korean hanja) count as 2; other characters count
as 1, including kana and Hangul (about 50 Han characters or 100
English characters). Exceeding the limit returns `400`
**Examples:**
- `用欢快、热情的语气说` (speak cheerfully and enthusiastically)
- `请用上海话表达` (use Shanghainese; multilingual and dialect voices)
- `Speak slowly in a calm and gentle tone`
Instructions do not count toward input tokens, but can change the
generated audio duration and therefore output tokens
> The parameter is `instruction` (singular); `instructions` returns
`400`
example: 用欢快、热情的语气说
language:
type: string
description: >-
Target-language hint to improve the reading of numbers,
abbreviations, and symbols, and synthesis in less common languages
For example, with `zh`, `110` in `hello, this is 110` is read as
“yao yao ling” in Chinese
| Value | Language | Value | Language |
|---|---|---|---|
| `zh` | Chinese | `th` | Thai |
| `en` | English | `id` | Indonesian |
| `fr` | French | `vi` | Vietnamese |
| `de` | German | `es` | Spanish |
| `ja` | Japanese | `it` | Italian |
| `ko` | Korean | `ms` | Malay |
| `ru` | Russian | `fil` | Filipino |
| `pt` | Portuguese | `ar` | Arabic |
The model detects the language if omitted; this parameter does not
translate text
enum:
- zh
- en
- fr
- de
- ja
- ko
- ru
- pt
- th
- id
- vi
- es
- it
- ms
- fil
- ar
example: zh
enable_ssml:
type: boolean
description: >-
Parse `prompt` as SSML
When enabled, SSML tags can be used, such as ``
for a pause:
`欢迎收听今天的节目。我们马上开始。`
Pauses inserted with SSML do not count toward output tokens
default: false
example: false
hot_fix:
type: object
description: >-
Custom pronunciation and text replacement to correct polyphonic
characters, proper names, and other pronunciations
- `pronunciation`: annotate words with pinyin (separate syllables
with spaces and mark tones with digits, such as `tian1 qi4`) to
override the default pronunciation
- `replace`: replace specified words before synthesis. Synthesis and
billing use the replaced text, which must also stay within `5000`
characters; exceeding the limit returns `400` (`prompt_too_long`)
The two lists may contain at most `200` entries in total, counted as
key-value pairs within the objects. Exceeding the limit returns
`400` (`invalid_parameter`)
Provide at least one list. Each provided list must be a non-empty
array of objects in `{"word": "value"}` form
**Example:**
```json
{
"pronunciation": [{"天气": "tian1 qi4"}],
"replace": [{"今天": "金天"}]
}
```
properties:
pronunciation:
type: array
description: >-
Custom pronunciation list; each item is an object such as
`{"word": "pinyin"}`
items:
type: object
additionalProperties:
type: string
example:
- 天气: tian1 qi4
replace:
type: array
description: >-
Text replacement list; each item is an object such as
`{"original word": "replacement text"}`
items:
type: object
additionalProperties:
type: string
example:
- 今天: 金天
enable_aigc_tag:
type: boolean
description: >-
Embed an invisible AIGC marker in generated audio (applies to `wav`
/ `mp3` / `opus`)
default: false
example: false
callback_url:
type: string
description: >-
HTTPS callback URL for the task result
**Timing:**
- Triggered when the task completes (`completed`) or fails
(`failed`); this model does not support cancellation
- Sent after billing has been confirmed
**Security requirements:**
- HTTPS only
- Private-network IPs are prohibited (127.0.0.1, 10.x.x.x,
172.16–31.x.x, 192.168.x.x, etc.)
- URL length at most `2048` characters
**Delivery:**
- Timeout: `10` seconds
- At most `3` retries after failure, with delays of `1` / `2` / `4`
seconds
- The callback body has the same format as the task query response
- A 2xx status is success; other statuses trigger retries
format: uri
example: https://your-domain.com/webhooks/tts-completed
QwenAudioTtsResponse:
type: object
properties:
created:
type: integer
description: Task creation timestamp
example: 1790000000
id:
type: string
description: Task ID
example: task-unified-1790000000-abcd1234
model:
type: string
description: Model actually used
example: qwen-audio-3.1-tts-flash
object:
type: string
enum:
- audio.generation.task
description: Specific task object type
progress:
type: integer
description: Task progress percentage (0–100)
minimum: 0
maximum: 100
example: 0
status:
type: string
description: Task status
enum:
- pending
- processing
- completed
- failed
example: pending
task_info:
$ref: '#/components/schemas/AudioTaskInfo'
description: Audio task details
type:
type: string
enum:
- audio
description: Task output type
example: audio
usage:
$ref: '#/components/schemas/AudioUsage'
description: Usage and billing information
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Error code identifier
message:
type: string
description: Error message
type:
type: string
description: Error type
AudioTaskInfo:
type: object
properties:
can_cancel:
type: boolean
description: >-
Whether the task can be canceled (this model does not support
cancellation)
example: false
estimated_time:
type: integer
description: >-
Estimated completion time in seconds; increases with text length, up
to about `90` seconds
minimum: 0
example: 3
audio_type:
type: string
description: Audio task type
example: tts
AudioUsage:
type: object
description: Usage information
properties:
credits_reserved:
type: number
description: >-
Credits reserved based on text length; settled against actual token
usage on completion, with excess refunded or shortfall charged
minimum: 0
example: 0.0144
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
## Bearer token authentication is required for all endpoints
**Get an API key:**
Visit [API Key Management](https://evolink.ai/dashboard/keys) to obtain
your API key
**Add this request header:**
```
Authorization: Bearer YOUR_API_KEY
```
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.