# Qwen Audio 3.1 TTS Plus 语音合成

> 音频生成

将文本合成为语音。默认返回包含音频 URL 或 Base64 音频的 JSON；当 `metadata.stream` 为 `true` 时返回 `text/event-stream`，按句逐个推送音频块，最后一帧携带用量信息。

`input`、`voice` 为必填字段，`instructions`、`speed`、`response_format`、`audio_config` 为可选。未显式指定格式时上游默认使用 `mp3`、采样率 `22050`。

## 请求地址

`POST https://api.modelverse.cn/v1/audio/speech`

## 请求体

## 响应

- **200** — 合成成功。非流式返回 JSON（音频 URL 有效期 24 小时）；`metadata.stream=true` 时返回 `text/event-stream`。

- **400** — 请求参数无效，或音色与模型不匹配。上游首个事件即为错误时，接口直接返回该错误，不会输出半截事件流。

- **401** — 鉴权失败，API Key 缺失或无效。
- **default** — 其他错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Qwen Audio 3.1 TTS Plus 语音合成",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 `qwen-audio-3.1-tts-plus` 的语音合成接口文档，说明如何提交文本、读取音频结果、开启 SSE 流式输出以及处理错误。\n\n接口路径为 `POST /v1/audio/speech`。\n\n## 模型特性\n\n- 非实时语音合成，单次提交完整文本，支持非流式（一次返回完整音频）和 SSE 流式（逐句返回音频块）两种输出方式。\n- 旗舰音色，支持 SSML、指令控制与字级时间戳，适合对音质和表现力要求更高的场景。\n- 支持中文普通话、多语种与方言，可通过 `voice` 选择音色、通过 `instructions` 控制情感、语速、方言等表达。\n\n## 计费口径\n\n`qwen-audio-3.1-tts-plus` 按**字符数**计费，用量体现在响应的 `usage.characters` 中。响应中的 `usage.input_tokens`、`usage.output_tokens`、`usage.total_tokens` 由上游返回，但不作为本模型的计费依据。\n\n## 使用注意\n\n- `voice` 必须属于 `qwen-audio-3.1-tts-plus` 的音色列表，音色与模型不可跨模型混用。音色不匹配时上游返回 `InvalidParameter`，错误信息形如 `[cosyvoice:]Engine error [411]: TTS speak operation failed`。\n- `instructions` 长度不能超过 100 个等效字符，计数时汉字按 2 个字符计算。\n- 流式输出通过请求体 `metadata.stream=true` 开启，服务端会向上游追加 `X-DashScope-SSE: enable` 请求头。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 生产环境地址。"
    }
  ],
  "tags": [
    {
      "name": "Qwen TTS",
      "description": "`qwen-audio-3.1-tts-plus` 的语音合成接口。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "Qwen TTS"
        ],
        "operationId": "createQwenAudio31TTSPlusSpeech",
        "summary": "Qwen Audio 3.1 TTS Plus 语音合成",
        "description": "将文本合成为语音。默认返回包含音频 URL 或 Base64 音频的 JSON；当 `metadata.stream` 为 `true` 时返回 `text/event-stream`，按句逐个推送音频块，最后一帧携带用量信息。\n\n`input`、`voice` 为必填字段，`instructions`、`speed`、`response_format`、`audio_config` 为可选。未显式指定格式时上游默认使用 `mp3`、采样率 `22050`。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QwenAudioTTSPlusSpeechRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础合成（WAV / 24kHz）",
                  "value": {
                    "model": "qwen-audio-3.1-tts-plus",
                    "input": "你好，今天的天气真不错。",
                    "voice": "longanhuan_v3.1",
                    "response_format": "wav",
                    "audio_config": {
                      "format": "wav",
                      "sample_rate": 24000
                    }
                  }
                },
                "withInstructions": {
                  "summary": "使用指令控制情感与语速",
                  "value": {
                    "model": "qwen-audio-3.1-tts-plus",
                    "input": "今天上海晴转多云，最高气温 22 度。",
                    "voice": "xunanchuan_v3.1",
                    "instructions": "用沉稳、专业的播报语气",
                    "speed": 0.9,
                    "response_format": "mp3"
                  }
                },
                "stream": {
                  "summary": "SSE 流式合成",
                  "value": {
                    "model": "qwen-audio-3.1-tts-plus",
                    "input": "这是一段流式合成的示例文本。",
                    "voice": "longanlingxin_v3.1",
                    "response_format": "pcm",
                    "audio_config": {
                      "format": "pcm",
                      "sample_rate": 24000
                    },
                    "metadata": {
                      "stream": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "合成成功。非流式返回 JSON（音频 URL 有效期 24 小时）；`metadata.stream=true` 时返回 `text/event-stream`。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenAudioTTSResponse"
                },
                "examples": {
                  "synthesizedSpeech": {
                    "summary": "非流式合成结果",
                    "value": {
                      "request_id": "5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
                      "output": {
                        "finish_reason": "stop",
                        "audio": {
                          "data": "",
                          "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xx/xxxxxxxx.wav?Expires=1766113409&OSSAccessKeyId=LTAI5xxxxxx&Signature=xxxxxx",
                          "id": "audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
                          "expires_at": 1766113409
                        }
                      },
                      "usage": {
                        "input_tokens": 12,
                        "output_tokens": 30,
                        "total_tokens": 42,
                        "characters": 22
                      }
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE 事件流。每个事件由 `id:`、`event:result`、`:HTTP_STATUS/200`、`data:<JSON>` 与一个空行组成，事件内容与阿里云原生格式一致。\n\n`output.audio.data` 为 Base64 音频块，按事件顺序拼接后可还原完整音频；`output.type` 取值为 `sentence-begin`、`sentence-synthesis`、`sentence-end`。终止帧 `output.finish_reason=stop`，并携带 `usage`。\n"
                },
                "examples": {
                  "streamEvents": {
                    "summary": "流式事件示例（节选）",
                    "value": "id:1\nevent:result\n:HTTP_STATUS/200\ndata:{\"output\":{\"finish_reason\":null,\"type\":\"sentence-begin\",\"original_text\":\"这是一段流式合成的示例文本。\",\"sentence\":{\"index\":0,\"words\":[]},\"audio\":{\"data\":\"\",\"id\":\"audio_xxxx\",\"expires_at\":1766113409}},\"request_id\":\"5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx\"}\n\nid:2\nevent:result\n:HTTP_STATUS/200\ndata:{\"output\":{\"finish_reason\":null,\"type\":\"sentence-synthesis\",\"sentence\":{\"index\":0},\"audio\":{\"data\":\"UklGRiQAAABXQVZF...\",\"id\":\"audio_xxxx\",\"expires_at\":1766113409}},\"request_id\":\"5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx\"}\n\nid:3\nevent:result\n:HTTP_STATUS/200\ndata:{\"output\":{\"finish_reason\":\"stop\",\"type\":\"sentence-end\",\"audio\":{\"data\":\"\",\"id\":\"audio_xxxx\",\"expires_at\":1766113409}},\"usage\":{\"input_tokens\":12,\"output_tokens\":30,\"total_tokens\":42,\"characters\":22},\"request_id\":\"5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx\"}\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效，或音色与模型不匹配。上游首个事件即为错误时，接口直接返回该错误，不会输出半截事件流。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenAudioTTSErrorResponse"
                },
                "examples": {
                  "invalidVoice": {
                    "summary": "音色与模型不匹配",
                    "value": {
                      "error": {
                        "message": "[trace_id: 73bb3306-cb43-464f-9d62-0ae10601dfa9] Request llm server Error: upstream error: sse status=400, body=id:1\nevent:error\n:HTTP_STATUS/400\ndata:{\"code\":\"InvalidParameter\",\"message\":\"[cosyvoice:]Engine error [411]: TTS speak operation failed\",\"request_id\":\"7d610784-8df4-9244-9544-26b338145fd6\"}",
                        "type": "internal_error",
                        "code": "model_server_error",
                        "param": null,
                        "trace_id": "73bb3306-cb43-464f-9d62-0ae10601dfa9"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败，API Key 缺失或无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenAudioTTSErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "其他错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QwenAudioTTSErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "使用 Bearer Token 鉴权，格式为 `Authorization: Bearer <API Key>`。"
      }
    },
    "schemas": {
      "QwenAudioTTSPlusSpeechRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input",
          "voice"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "qwen-audio-3.1-tts-plus",
            "description": "模型名称，固定为 `qwen-audio-3.1-tts-plus`。"
          },
          "input": {
            "type": "string",
            "description": "待合成文本。支持纯文本、SSML（需同时设置 `metadata.enable_ssml=true`）与 LaTeX。\n文本过长会增加合成耗时，建议按句或按段拆分后分别请求。\n"
          },
          "voice": {
            "type": "string",
            "description": "音色 ID，必填，必须属于 `qwen-audio-3.1-tts-plus` 支持的音色列表，不能与其他模型混用。\n音色不匹配时上游返回 `InvalidParameter`（`[cosyvoice:]Engine error [411]`）。\n\n旗舰音色示例：`longanlingxin_v3.1`、`xunanchuan_v3.1`、`longanhuan_v3.1`、`longanfengyue_v3.1`，均支持 SSML、指令控制与时间戳。\n",
            "examples": [
              "longanlingxin_v3.1",
              "xunanchuan_v3.1",
              "longanhuan_v3.1",
              "longanfengyue_v3.1"
            ]
          },
          "instructions": {
            "type": "string",
            "description": "合成控制指令，对应上游 `input.instruction`，用于指定情感、语气、方言或角色。\n长度不能超过 100 个等效字符，汉字按 2 个字符计算。\n",
            "examples": [
              "用沉稳、专业的播报语气",
              "请讲上海话。"
            ]
          },
          "speed": {
            "type": "number",
            "format": "float",
            "minimum": 0.5,
            "maximum": 2,
            "default": 1,
            "description": "语速，对应上游 `input.rate`，取值范围 `[0.5, 2.0]`。"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "mp3",
              "pcm",
              "wav",
              "opus"
            ],
            "default": "mp3",
            "description": "音频编码格式，对应上游 `input.format`。与 `audio_config.format` 同时传入时以 `audio_config.format` 为准。"
          },
          "audio_config": {
            "$ref": "#/components/schemas/QwenAudioTTSAudioConfig"
          },
          "metadata": {
            "$ref": "#/components/schemas/QwenAudioTTSMetadata"
          }
        }
      },
      "QwenAudioTTSAudioConfig": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "mp3",
              "pcm",
              "wav",
              "opus"
            ],
            "description": "音频编码格式，优先级高于 `response_format`。"
          },
          "sample_rate": {
            "type": "integer",
            "enum": [
              8000,
              12000,
              16000,
              22050,
              24000,
              44100,
              48000
            ],
            "description": "音频采样率（Hz），对应上游 `input.sample_rate`，默认 `22050`。\n`format=opus` 时仅支持 `8000`、`12000`、`16000`、`24000`、`48000`。\n"
          }
        }
      },
      "QwenAudioTTSMetadata": {
        "type": "object",
        "additionalProperties": true,
        "description": "扩展参数对象。除上述字段外，其余键会作为阿里云原生字段透传到上游 `input`（如 `bit_rate`、`hot_fix`），已由协议层映射的字段（`text`、`voice`、`format`、`sample_rate`、`rate`、`instruction`）不会被覆盖。\n",
        "properties": {
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否以 SSE 流式返回音频。为 `true` 时响应类型为 `text/event-stream`。\n该字段只用于切换输出方式，不会透传给上游。\n"
          },
          "volume": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 50,
            "description": "音量，对应上游 `input.volume`。"
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "minimum": 0.5,
            "maximum": 2,
            "default": 1,
            "description": "音调，对应上游 `input.pitch`。"
          },
          "language_hints": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "合成目标语言提示，对应上游 `input.language_hints`，当前仅处理数组第一个元素。\n可选值包括 `zh`、`en`、`ja`、`ko`、`fr`、`de`、`ru`、`pt`、`es`、`it`、`th`、`id`、`vi`、`ms`、`fil`、`ar` 等。\n"
          },
          "enable_ssml": {
            "type": "boolean",
            "default": false,
            "description": "是否按 SSML 解析 `input`，对应上游 `input.enable_ssml`。"
          },
          "seed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 65535,
            "default": 0,
            "description": "随机种子，对应上游 `input.seed`。相同参数下使用相同 `seed` 可复现合成结果。"
          },
          "enable_aigc_tag": {
            "type": "boolean",
            "default": false,
            "description": "是否在音频中嵌入 AIGC 隐性标识，对应上游 `input.enable_aigc_tag`。"
          }
        }
      },
      "QwenAudioTTSResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "output"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "本次请求的唯一标识，用于排查问题。"
          },
          "output": {
            "$ref": "#/components/schemas/QwenAudioTTSOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/QwenAudioTTSUsage"
          }
        }
      },
      "QwenAudioTTSOutput": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "finish_reason",
          "audio"
        ],
        "properties": {
          "finish_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "stop",
              null
            ],
            "description": "合成状态。`null` 表示合成中，`stop` 表示合成结束。"
          },
          "type": {
            "type": "string",
            "enum": [
              "sentence-begin",
              "sentence-synthesis",
              "sentence-end"
            ],
            "description": "仅流式返回。`sentence-begin` 为句子开始，`sentence-synthesis` 为音频块（同一句可包含多个块），`sentence-end` 为句子结束并返回用量。"
          },
          "original_text": {
            "type": "string",
            "description": "用户输入文本切分后的句子内容，最后一句可能没有该字段。"
          },
          "sentence": {
            "type": "object",
            "additionalProperties": true,
            "description": "句子信息，含 `index` 与字级时间戳 `words`。"
          },
          "audio": {
            "$ref": "#/components/schemas/QwenAudioTTSAudio"
          }
        }
      },
      "QwenAudioTTSAudio": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "url",
          "id",
          "expires_at"
        ],
        "properties": {
          "data": {
            "type": "string",
            "description": "流式输出的 Base64 音频块；非流式输出时为空字符串。"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "完整音频文件的下载地址，有效期 24 小时；流式的中间事件可能不返回该字段。"
          },
          "id": {
            "type": "string",
            "description": "合成音频的标识。"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "音频 URL 的过期时间戳（秒）。"
          }
        }
      },
      "QwenAudioTTSUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "characters": {
            "type": "integer",
            "minimum": 0,
            "description": "累计字符数，为本模型的计费依据。"
          },
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "输入 Token 数，由上游返回，本模型不作为计费依据。"
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "输出 Token 数，由上游返回，本模型不作为计费依据。"
          },
          "total_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "输入与输出 Token 数之和，由上游返回，本模型不作为计费依据。"
          }
        }
      },
      "QwenAudioTTSErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/QwenAudioTTSError"
          }
        }
      },
      "QwenAudioTTSError": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明，上游错误会附带原始响应体。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error",
              "internal_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "model_server_error"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "出错的参数字段，无对应参数时为 `null`。"
          },
          "trace_id": {
            "type": "string",
            "description": "本次请求的追踪 ID，用于反馈与排查。"
          }
        }
      }
    }
  }
}
```