{
  "openapi": "3.0.3",
  "info": {
    "title": "Noiz Voice Open API (Agent Edition)",
    "description": "面向 Coze / Dify / 飞书等 Agent 工作流的语音 / 文本能力接入。所有接口通过 header `sign` 鉴权（旗舰会员 API Key）。\n\n**v1.1.0 变更**\n- 方言与多语言：`targetSpeech` 支持 57 个取值（普通话/英语 + 12 种中文方言 + 43 种独立语言），推荐显式提交；不传时服务端仍按文本自动判定语言。\n- 情绪控制：`genre` 支持 0/1/2 三种方式——跟随参考音频、情绪向量(`ext`)、情绪参考音频(`emotionPath`)，仅 style=2（V2.5）生效（style=3 方言/多语言不支持情绪控制）；Web 端属专业会员能力，旗舰会员 API Key 调用本接口默认可用。\n- 语速上限由 1.5 放开到 2.0。",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "http://openapi.anyvoice.cn",
      "description": "当前部署"
    }
  ],
  "components": {
    "securitySchemes": {
      "SignAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "sign",
        "description": "旗舰会员的 API Key（向平台申请获取）"
      }
    },
    "schemas": {
      "BaseResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "业务码：0=成功；7=通用失败；1001=字数超限"
          },
          "msg": {
            "type": "string"
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "code",
          "msg"
        ]
      },
      "TtsRequest": {
        "type": "object",
        "required": [
          "content",
          "audioId",
          "style"
        ],
        "properties": {
          "content": {
            "type": "string",
            "description": "要合成的文本内容"
          },
          "audioId": {
            "type": "string",
            "description": "参考音频/音色 ID。可通过 /api/third/reference/list 获取"
          },
          "style": {
            "type": "string",
            "enum": [
              "1",
              "2",
              "3"
            ],
            "description": "模型版本：1=V2.0，2=V2.5（支持情绪控制），3=方言/多语言。\n注意：传了 targetSpeech 且该语言不支持所选 style 时，服务端会强制改写为 3，响应与结果里返回的是改写后的值。"
          },
          "speed": {
            "type": "number",
            "format": "float",
            "minimum": 0.5,
            "maximum": 2.0,
            "default": 1.0,
            "description": "语速，0.5-2.0，必须为一位小数（如 0.8/1.0/1.2）。落库与回显是原始值；方言/多语言链路模型上限只有 1.5，服务端会在下发前自动压缩，不影响入参校验。"
          },
          "targetSpeech": {
            "$ref": "#/components/schemas/TargetSpeech"
          },
          "genre": {
            "type": "integer",
            "enum": [
              0,
              1,
              2
            ],
            "default": 0,
            "description": "情绪控制方式，**仅 style=2（V2.5）实际生效**（style=1 只能传 0）：\n- 0 = 跟随参考音频的情绪（默认，不需要额外参数）\n- 1 = 情绪向量，用 ext 指定 8 个维度的强度\n- 2 = 情绪参考音频，用 emotionPath 指定一段音频，从中提取情绪\n\n⚠️ style=3（方言/多语言）不支持情绪控制，接口会放行 genre/ext/emotionPath，但不会生效。方言/多语言若需要情绪控制，请选支持 style=2 的语言（mandarin/english/ja/es/ar）。\n\n情绪控制在 Web 端属专业会员能力；通过本接口调用时，旗舰会员 API Key 默认即可使用，无需额外开通。"
          },
          "ext": {
            "type": "object",
            "description": "情绪向量，仅 style=2（V2.5）且 genre=1 时生效。8 个维度各自取值 [0,1]，可同时给多个维度赋值。传了未知字段会直接报错。style=3 下该字段被忽略。",
            "properties": {
              "happy": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "angry": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "sad": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "afraid": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "disgusted": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "melancholic": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "surprised": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              },
              "calm": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1
              }
            }
          },
          "emotionPath": {
            "type": "string",
            "description": "情绪参考音频的文件名，genre=2 时必填。需先调用 POST /api/third/file/uploadCustom 上传音频，用返回的文件名填在这里。该文件属于临时文件，会被定时清理，过期需重新上传。仅 style=2（V2.5）生效，style=3 下该字段被忽略。"
          }
        }
      },
      "TtsResponse": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string",
            "description": "任务 ID"
          },
          "status": {
            "type": "integer",
            "description": "1=处理中，2=已完成，3=失败"
          },
          "voiceUrl": {
            "type": "string",
            "description": "合成音频 URL（status=2 时有值）"
          }
        }
      },
      "ReferenceAudioItem": {
        "type": "object",
        "properties": {
          "audioId": {
            "type": "string",
            "description": "声音模型 ID，传给 /tts/sync、/tts/create 的 audioId"
          },
          "name": {
            "type": "string",
            "description": "声音模型名称"
          },
          "describe": {
            "type": "string",
            "description": "备注描述，可能为空"
          }
        }
      },
      "ReferenceAudioUploadResponse": {
        "type": "object",
        "properties": {
          "audioId": {
            "type": "string",
            "description": "模型ID，语音合成时作为 audioId 使用"
          },
          "name": {
            "type": "string",
            "description": "模型名称"
          },
          "describe": {
            "type": "string",
            "description": "模型描述"
          }
        }
      },
      "CustomFileResponse": {
        "type": "object",
        "properties": {
          "emotionPath": {
            "type": "string",
            "description": "情绪参考音频文件名，创建 TTS 时作为 emotionPath 回传"
          }
        }
      },
      "DenoiseUploadResponse": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string",
            "description": "降噪任务ID，用于 /denoise/poll 轮询"
          }
        }
      },
      "DenoiseResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "completed",
              "failed"
            ],
            "description": "任务状态"
          },
          "filePath": {
            "type": "string",
            "description": "降噪结果文件地址，status=completed 时返回"
          },
          "message": {
            "type": "string",
            "description": "失败原因，status=failed 时返回"
          }
        }
      },
      "TargetSpeech": {
        "type": "string",
        "title": "目标语言/方言",
        "description": "语音合成的目标语言或方言，非必填但**推荐显式提交**；不传时服务端按文本内容自动判定，短文本或中英混排容易判错。\n\n分三类：\n1. `mandarin` / `english`：style 1/2/3 都支持，可用情绪控制。\n2. `ja` / `es` / `ar`：style=2（V2.5）可用情绪控制；style=3 走方言/多语言模型；style=1 会被升为 3。\n3. 其余 52 个（12 种中文方言 + 40 种独立语言）：**style 最好都传 3**，不支持情绪控制。\n\n**枚举外的语言怎么办**：传了枚举外的取值会直接报错「暂不支持该语言」，任务不会创建。这种情况请改为 `style=3` 且 **不传 targetSpeech**（留空），此时服务端不下发语言参数，由方言/多语言模型按文本自行处理，常见语种都能正常合成。\n\n只提交本字段即可，其余模型参数由服务端映射，调用方不需要关心。",
        "enum": [
          "mandarin",
          "english",
          "henan",
          "shaanxi",
          "sichuan",
          "guizhou",
          "yunnan",
          "guilin",
          "jinan",
          "shijiazhuang",
          "gansu",
          "ningxia",
          "qingdao",
          "northeast",
          "yue",
          "nan",
          "ug",
          "bo",
          "mn",
          "kk",
          "ky",
          "ja",
          "ko",
          "es",
          "fr",
          "de",
          "ru",
          "pt",
          "it",
          "th",
          "vi",
          "id",
          "ms",
          "ar",
          "hi",
          "fa",
          "tr",
          "ur",
          "bn",
          "ta",
          "nl",
          "pl",
          "sv",
          "no",
          "da",
          "fi",
          "el",
          "cs",
          "hu",
          "uk",
          "he",
          "fil",
          "my",
          "km",
          "lo",
          "ne",
          "sw"
        ],
        "x-apifox-enum": [
          {
            "value": "mandarin",
            "name": "普通话",
            "description": "style 1/2/3 均可，支持情绪控制"
          },
          {
            "value": "english",
            "name": "英语",
            "description": "style 1/2/3 均可，支持情绪控制"
          },
          {
            "value": "henan",
            "name": "河南话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "shaanxi",
            "name": "陕西话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "sichuan",
            "name": "四川话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "guizhou",
            "name": "贵州话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "yunnan",
            "name": "云南话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "guilin",
            "name": "桂林话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "jinan",
            "name": "济南话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "shijiazhuang",
            "name": "石家庄话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "gansu",
            "name": "甘肃话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ningxia",
            "name": "宁夏话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "qingdao",
            "name": "青岛话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "northeast",
            "name": "东北话",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "yue",
            "name": "粤语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "nan",
            "name": "闽南语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ug",
            "name": "维吾尔语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "bo",
            "name": "藏语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "mn",
            "name": "蒙古语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "kk",
            "name": "哈萨克语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ky",
            "name": "柯尔克孜语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ja",
            "name": "日语",
            "description": "style=2（V2.5）支持情绪控制；style=3 走方言/多语言模型；style=1 会被升为 3"
          },
          {
            "value": "ko",
            "name": "韩语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "es",
            "name": "西班牙语",
            "description": "style=2（V2.5）支持情绪控制；style=3 走方言/多语言模型；style=1 会被升为 3"
          },
          {
            "value": "fr",
            "name": "法语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "de",
            "name": "德语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ru",
            "name": "俄语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "pt",
            "name": "葡萄牙语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "it",
            "name": "意大利语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "th",
            "name": "泰语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "vi",
            "name": "越南语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "id",
            "name": "印尼语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ms",
            "name": "马来语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ar",
            "name": "阿拉伯语",
            "description": "style=2（V2.5）支持情绪控制；style=3 走方言/多语言模型；style=1 会被升为 3"
          },
          {
            "value": "hi",
            "name": "印地语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "fa",
            "name": "波斯语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "tr",
            "name": "土耳其语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ur",
            "name": "乌尔都语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "bn",
            "name": "孟加拉语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ta",
            "name": "泰米尔语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "nl",
            "name": "荷兰语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "pl",
            "name": "波兰语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "sv",
            "name": "瑞典语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "no",
            "name": "挪威语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "da",
            "name": "丹麦语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "fi",
            "name": "芬兰语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "el",
            "name": "希腊语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "cs",
            "name": "捷克语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "hu",
            "name": "匈牙利语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "uk",
            "name": "乌克兰语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "he",
            "name": "希伯来语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "fil",
            "name": "菲律宾语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "my",
            "name": "缅甸语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "km",
            "name": "高棉语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "lo",
            "name": "老挝语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "ne",
            "name": "尼泊尔语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          },
          {
            "value": "sw",
            "name": "斯瓦希里语",
            "description": "强制 style=3（方言/多语言），不支持情绪控制"
          }
        ]
      }
    }
  },
  "security": [
    {
      "SignAuth": []
    }
  ],
  "paths": {
    "/api/third/reference/upload": {
      "post": {
        "operationId": "referenceUpload",
        "summary": "创建克隆模型（上传参考音频）",
        "tags": [
          "克隆模型"
        ],
        "description": "上传一段音频作为音色参考，返回 audioId，作为后续 TTS 的 audioId 使用。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "name"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "音频文件，支持 mp3/wav/m4a，≤50MB，时长 2-60 秒"
                  },
                  "name": {
                    "type": "string",
                    "description": "模型名称"
                  },
                  "describe": {
                    "type": "string",
                    "description": "模型描述，选填"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/ReferenceAudioUploadResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/reference/list": {
      "get": {
        "operationId": "referenceList",
        "summary": "查询可用声音模型列表",
        "description": "返回当前账号下全部可用的声音模型（含接口上传的参考音频与网页端创建的声音模型），作为 TTS 的 audioId 候选。",
        "tags": [
          "克隆模型"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "list": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ReferenceAudioItem"
                              }
                            },
                            "total": {
                              "type": "integer"
                            },
                            "page": {
                              "type": "integer"
                            },
                            "pageSize": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/reference/delete": {
      "delete": {
        "operationId": "referenceDelete",
        "summary": "删除克隆模型",
        "tags": [
          "克隆模型"
        ],
        "parameters": [
          {
            "name": "audioId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "模型ID"
          }
        ],
        "responses": {
          "200": {
            "description": "删除成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/file/uploadCustom": {
      "post": {
        "operationId": "uploadCustomEmotion",
        "summary": "上传情绪参考音频（TTS genre=2 用）",
        "tags": [
          "TTS"
        ],
        "description": "上传一段带目标情绪的音频，返回文件名，填入 TTS 请求的 emotionPath。属临时文件，会被定时清理，过期需重新上传。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "音频文件，支持 mp3/wav/m4a，≤50MB，时长 2-60 秒"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/CustomFileResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/tts/sync": {
      "post": {
        "operationId": "ttsSync",
        "summary": "同步语音合成（推荐 Agent 使用）",
        "description": "提交合成任务并内部轮询直至完成。最长等待 90 秒；若超时则返回 taskId，调用方可调 /tts/result 兜底查询。",
        "tags": [
          "TTS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TtsRequest"
              },
              "examples": {
                "基础-普通话": {
                  "summary": "普通话，默认情绪",
                  "value": {
                    "content": "今天天气不错，适合出门走走。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "speed": 1.0
                  }
                },
                "方言-四川话": {
                  "summary": "方言，服务端强制走 style=3",
                  "value": {
                    "content": "今天天气巴适得很，等哈儿我们一起切喝杯茶嘛。",
                    "audioId": "role_xxx",
                    "style": "3",
                    "targetSpeech": "sichuan",
                    "speed": 1.0
                  }
                },
                "多语言-日语": {
                  "summary": "日语走 V2.5(style=2)",
                  "value": {
                    "content": "今日はいい天気ですね。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "ja",
                    "speed": 1.0
                  }
                },
                "情绪-向量(genre=1)": {
                  "summary": "用 ext 指定情绪强度",
                  "value": {
                    "content": "太好了，我们终于成功了！",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "genre": 1,
                    "ext": {
                      "happy": 0.8,
                      "surprised": 0.3
                    }
                  }
                },
                "情绪-参考音频(genre=2)": {
                  "summary": "先调 /api/third/file/uploadCustom 拿文件名",
                  "value": {
                    "content": "这件事我们必须马上处理。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "genre": 2,
                    "emotionPath": "20260817_xxxxxx.wav"
                  }
                },
                "枚举外语言-罗马尼亚语": {
                  "summary": "枚举外语言：style=3 且不传 targetSpeech",
                  "value": {
                    "content": "Bună ziua, ce mai faceți?",
                    "audioId": "role_xxx",
                    "style": "3",
                    "speed": 1.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "合成完成 / 处理中 / 失败",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TtsResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/tts/create": {
      "post": {
        "operationId": "ttsCreate",
        "summary": "创建语音合成任务（异步）",
        "description": "提交合成任务后立即返回 taskId，请通过 /tts/result 轮询结果。需要更长合成时间或自定义轮询节奏时使用。",
        "tags": [
          "TTS"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TtsRequest"
              },
              "examples": {
                "基础-普通话": {
                  "summary": "普通话，默认情绪",
                  "value": {
                    "content": "今天天气不错，适合出门走走。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "speed": 1.0
                  }
                },
                "方言-四川话": {
                  "summary": "方言，服务端强制走 style=3",
                  "value": {
                    "content": "今天天气巴适得很，等哈儿我们一起切喝杯茶嘛。",
                    "audioId": "role_xxx",
                    "style": "3",
                    "targetSpeech": "sichuan",
                    "speed": 1.0
                  }
                },
                "多语言-日语": {
                  "summary": "日语走 V2.5(style=2)",
                  "value": {
                    "content": "今日はいい天気ですね。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "ja",
                    "speed": 1.0
                  }
                },
                "情绪-向量(genre=1)": {
                  "summary": "用 ext 指定情绪强度",
                  "value": {
                    "content": "太好了，我们终于成功了！",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "genre": 1,
                    "ext": {
                      "happy": 0.8,
                      "surprised": 0.3
                    }
                  }
                },
                "情绪-参考音频(genre=2)": {
                  "summary": "先调 /api/third/file/uploadCustom 拿文件名",
                  "value": {
                    "content": "这件事我们必须马上处理。",
                    "audioId": "role_xxx",
                    "style": "2",
                    "targetSpeech": "mandarin",
                    "genre": 2,
                    "emotionPath": "20260817_xxxxxx.wav"
                  }
                },
                "枚举外语言-罗马尼亚语": {
                  "summary": "枚举外语言：style=3 且不传 targetSpeech",
                  "value": {
                    "content": "Bună ziua, ce mai faceți?",
                    "audioId": "role_xxx",
                    "style": "3",
                    "speed": 1.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已入队",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TtsResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/tts/result": {
      "get": {
        "operationId": "ttsResult",
        "summary": "查询语音合成结果",
        "tags": [
          "TTS"
        ],
        "parameters": [
          {
            "name": "taskId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "/tts/create 或 /tts/sync 返回的任务 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TtsResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/tts/list": {
      "get": {
        "operationId": "ttsList",
        "summary": "查询语音合成任务列表",
        "tags": [
          "TTS"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            },
            "description": "页码，默认1"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 30
            },
            "description": "每页条数，默认10，最大30"
          }
        ],
        "responses": {
          "200": {
            "description": "获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "list": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/TtsResponse"
                              }
                            },
                            "total": {
                              "type": "integer"
                            },
                            "page": {
                              "type": "integer"
                            },
                            "pageSize": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/denoise/upload": {
      "post": {
        "operationId": "denoiseUpload",
        "summary": "音频降噪（异步）",
        "tags": [
          "降噪"
        ],
        "description": "上传音频做降噪，返回 taskId，用 /denoise/poll 轮询。单用户进行中的降噪任务上限 5 个。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "音频文件，时长 3-60 秒"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DenoiseUploadResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/third/denoise/poll": {
      "get": {
        "operationId": "denoisePoll",
        "summary": "轮询降噪结果",
        "tags": [
          "降噪"
        ],
        "parameters": [
          {
            "name": "taskId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "降噪任务ID"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DenoiseResult"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "克隆模型",
      "description": "音色模型的创建与删除"
    },
    {
      "name": "TTS",
      "description": "语音合成与情绪控制"
    },
    {
      "name": "降噪",
      "description": "音频降噪"
    }
  ]
}