# Audio

Base URL `https://api.sniphunter.com`

音频处理、ASR、语音合成、克隆与变声。

# Audio


## POST /api/v1/audio/ai/align

Align Audio
词级强制对齐

输入音频 URL + 已有转写文本，返回词/句时间戳列表。
可与 /transcribe 组合：先转写再对齐。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AlignRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/enhance

Enhance Audio
人声增强 / 音频 AI 增强

mode: enhance | denoise
engine: mossformer2-se-sr（默认）| resemble

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EnhanceRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/ai/status

Get Ai Status
获取 AI 服务状态

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/transcribe

Transcribe Audio
语音转文字 (STT / ASR)

使用 Qwen3-ASR。可选 with_align=true 调用 forced-align 补词级时间戳。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TranscribeRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/tts

Text To Speech
文字转语音 (TTS) — EdgeTTS / Qwen3-TTS

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TTSRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/ai/tts/voices

Get Tts Voices
获取可用的 TTS 语音列表。

category: sample（Edge 全量→Qwen3 克隆）| qwen3 | edge | all
locale: 语种前缀或完整 locale（zh / zh-CN / en / en-US）
q: 搜索关键字

用户克隆音色请用 GET /tts/voices/mine（需登录）。

额外返回 languages：按语种聚合的数量，便于前端国际化语言选择。

```json
{
  "parameters": [
    {
      "name": "locale",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Locale"
      }
    },
    {
      "name": "gender",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Gender"
      }
    },
    {
      "name": "category",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Category"
      }
    },
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Q"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/ai/tts/voices/mine

Get My Tts Voices
获取当前用户已保存的克隆音色（文字配音「我的克隆」）。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## DELETE /api/v1/audio/ai/tts/voices/mine/{voice_id}

Delete My Tts Voice
删除我的克隆音色。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "voice_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Voice Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/vocal-separate

Vocal Separate
人声/伴奏分离

使用 Demucs AI 模型分离音频中的人声和背景音乐。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VocalSeparateRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/ai/voice-change/presets

List Voice Change Presets
检索常用变声目标音色示例（Qwen3-TTS 合成，可试听）。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Q"
      }
    },
    {
      "name": "gender",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Gender"
      }
    },
    {
      "name": "locale",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Locale"
      }
    },
    {
      "name": "ensure",
      "in": "query",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": false,
        "title": "Ensure"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/ai/voice-change/presets/{preset_id}

Get Voice Change Preset
单个变声预设；默认合成/返回 Qwen3 试听音。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "preset_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Preset Id"
      }
    },
    {
      "name": "ensure",
      "in": "query",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": true,
        "title": "Ensure"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/voice-clone

Voice Clone
音色克隆合成（Qwen3-TTS）

用参考音频即时克隆并合成 text；默认写入「我的克隆」音色库，
供文字配音通过 prompt_audio_url 复用。VIP 专属。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/src__api__v1__endpoints__audio__ai__VoiceCloneRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/voice-convert

Voice Convert
音频变声（Seed-VC）

将 source 音频内容转为参考音色；可用 preset_id（Qwen3 合成示例）或自定义 reference_url。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceConvertRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/voice-design

Voice Design
音色设计试听（Qwen3-TTS VoiceDesign）

用自然语言 instruct 描述音色并合成试听音频；确认后调用
POST /voice-design/save 写入「我的克隆」，供文字配音复用。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceDesignRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/ai/voice-design/save

Save Voice Design
确认使用设计音色：将试听音频作为参考音写入「我的克隆」。

不额外合成；后续文字配音通过 prompt_audio_url + Base 模型克隆复用。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceDesignSaveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/convert

Convert Format
音频格式转换

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ConvertFormatRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/extract

Extract Audio
从视频提取音频

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ExtractAudioRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/basic/formats

Get Supported Formats
获取支持的音频格式

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/merge

Merge Audio
音频拼接

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MergeAudioRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/mix

Mix Audio
混音（添加背景音乐）

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MixAudioRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/split

Split Audio
按时间切分音频（固定时长或等分 N 段）

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SplitAudioRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/basic/trim

Trim Audio
音频裁剪

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TrimAudioRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/effects/denoise

Denoise Audio
AI 音频降噪：engine=resemble（默认）| mossformer2-se

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DenoiseRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/effects/effects

List Voice Effects
常用变声目标音色（Seed-VC 预设；兼容旧 effects 字段名）。

```json
{
  "parameters": [
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Q"
      }
    },
    {
      "name": "gender",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Gender"
      }
    },
    {
      "name": "locale",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Locale"
      }
    },
    {
      "name": "ensure",
      "in": "query",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": false,
        "title": "Ensure"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/effects/fade

Fade Audio
淡入淡出

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FadeRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/effects/speed

Change Speed
变速

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SpeedRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/effects/voice-effect

Apply Voice Effect
变声效果

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceEffectRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/effects/volume

Adjust Volume
调整音量

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VolumeRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/tasks/enhance

Create Audio Enhance Task


```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AudioEnhanceTaskRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AsyncTaskCreateResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/tasks/transcribe

Create Transcribe Task
语音转写：提交时校验配额，成功后扣减

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TranscribeTaskRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AsyncTaskCreateResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/tasks/vocal-separate

Create Vocal Separate Task


```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VocalSeparateTaskRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AsyncTaskCreateResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/tasks/voice-convert

Create Voice Convert Task
音频变声（Seed-VC）：预设音色或自定义参考音。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceConvertTaskRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AsyncTaskCreateResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/voiceover/status

Get Voiceover Status
获取配音服务状态 (EdgeTTS)

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/audio/voiceover/synthesize

Synthesize Voiceover
配音合成（支持多段精细配置）

- 支持多段文本分别设置音色、语速、音调
- 支持段落间停顿控制
- 支持合并或分段输出

VIP 专属功能。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VoiceoverSynthesizeRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/voiceover/tts

Simple Tts
简单文字转语音

EdgeTTS（默认）或 Qwen3-TTS；提供 prompt_audio_url 时走克隆合成。VIP 专属。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SimpleTTSRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/voiceover/voices

Get Voices
获取可用音色列表

包括系统预设音色和用户克隆的音色。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "locale",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Locale"
      }
    },
    {
      "name": "gender",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Gender"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/voiceover/voices/clone

Clone Voice
音色克隆合成（Qwen3-TTS）

用参考音频即时克隆并合成 text；默认写入「我的克隆」音色库。VIP 专属。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/src__api__v1__endpoints__audio__voiceover__VoiceCloneRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/audio/voiceover/voices/clone/upload

Clone Voice Upload
上传参考音频并克隆合成。

支持 WAV、MP3、M4A，最大 10MB。需提供 text。默认写入音色库。VIP 专属。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "multipart/form-data": {
        "schema": {
          "$ref": "#/components/schemas/Body_clone_voice_upload_api_v1_audio_voiceover_voices_clone_upload_post"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/audio/voiceover/voices/my

Get My Voices
获取我的克隆音色列表

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## DELETE /api/v1/audio/voiceover/voices/{voice_id}

Delete Voice
删除克隆音色（支持数字 id 或 clone_{id}）

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "voice_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Voice Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "AlignRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "transcript": {
          "type": "string",
          "minLength": 1,
          "title": "Transcript",
          "description": "已有转写文本"
        },
        "language": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Language",
          "description": "对齐语言",
          "default": "Chinese"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "transcript"
      ],
      "title": "AlignRequest",
      "description": "词级对齐请求"
    },
    "AsyncTaskCreateResponse": {
      "properties": {
        "success": {
          "type": "boolean",
          "title": "Success",
          "default": true
        },
        "task_id": {
          "type": "integer",
          "title": "Task Id"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "default": "pending"
        },
        "message": {
          "type": "string",
          "title": "Message",
          "default": "任务已提交，正在处理中"
        },
        "progress_token": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Progress Token"
        },
        "estimated_time_seconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Estimated Time Seconds"
        },
        "created_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Created At"
        }
      },
      "type": "object",
      "required": [
        "task_id"
      ],
      "title": "AsyncTaskCreateResponse"
    },
    "AudioEnhanceTaskRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "mode": {
          "type": "string",
          "enum": [
            "enhance",
            "denoise"
          ],
          "title": "Mode",
          "description": "enhance=人声增强; denoise=转调 Moss 降噪",
          "default": "enhance"
        },
        "engine": {
          "type": "string",
          "enum": [
            "mossformer2-se-sr",
            "resemble"
          ],
          "title": "Engine",
          "description": "mossformer2-se-sr=SE→SR+低频回填（默认）; resemble=CFM+低频回填",
          "default": "mossformer2-se-sr"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "AudioEnhanceTaskRequest"
    },
    "Body_clone_voice_upload_api_v1_audio_voiceover_voices_clone_upload_post": {
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text"
        },
        "voice_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Name"
        },
        "prompt_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Text"
        },
        "language": {
          "type": "string",
          "title": "Language",
          "default": "Chinese"
        },
        "save_voice": {
          "type": "boolean",
          "title": "Save Voice",
          "default": true
        },
        "audio_file": {
          "type": "string",
          "format": "binary",
          "title": "Audio File"
        }
      },
      "type": "object",
      "required": [
        "text",
        "audio_file"
      ],
      "title": "Body_clone_voice_upload_api_v1_audio_voiceover_voices_clone_upload_post"
    },
    "ConvertFormatRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        },
        "bitrate": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bitrate"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "ConvertFormatRequest",
      "description": "音频格式转换请求"
    },
    "DenoiseRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp3"
        },
        "engine": {
          "type": "string",
          "enum": [
            "resemble",
            "mossformer2-se"
          ],
          "title": "Engine",
          "description": "resemble=Resemble UNet；mossformer2-se=MossFormer enhance_wav",
          "default": "resemble"
        },
        "strength": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Strength",
          "description": "已废弃，忽略"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "DenoiseRequest",
      "description": "音频降噪请求：resemble（默认）| mossformer2-se"
    },
    "EnhanceRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "mode": {
          "type": "string",
          "enum": [
            "enhance",
            "denoise"
          ],
          "title": "Mode",
          "description": "enhance=人声增强; denoise=转调 Moss 降噪",
          "default": "enhance"
        },
        "engine": {
          "type": "string",
          "enum": [
            "mossformer2-se-sr",
            "resemble"
          ],
          "title": "Engine",
          "description": "mossformer2-se-sr（默认）| resemble",
          "default": "mossformer2-se-sr"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "EnhanceRequest",
      "description": "人声增强 / 音频增强请求"
    },
    "ExtractAudioRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "minLength": 1,
          "title": "Video Url"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "ExtractAudioRequest",
      "description": "从视频提取音频请求"
    },
    "FadeRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "fade_in_duration": {
          "type": "number",
          "minimum": 0.0,
          "title": "Fade In Duration",
          "description": "淡入时长(秒)",
          "default": 1.0
        },
        "fade_out_duration": {
          "type": "number",
          "minimum": 0.0,
          "title": "Fade Out Duration",
          "description": "淡出时长(秒)",
          "default": 1.0
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "FadeRequest",
      "description": "淡入淡出请求"
    },
    "HTTPValidationError": {
      "properties": {
        "detail": {
          "items": {
            "$ref": "#/components/schemas/ValidationError"
          },
          "type": "array",
          "title": "Detail"
        }
      },
      "type": "object",
      "title": "HTTPValidationError"
    },
    "MergeAudioRequest": {
      "properties": {
        "audio_urls": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "minItems": 2,
          "title": "Audio Urls"
        },
        "interval": {
          "type": "number",
          "minimum": 0.0,
          "title": "Interval",
          "default": 0.0
        },
        "fade_duration": {
          "type": "number",
          "minimum": 0.0,
          "title": "Fade Duration",
          "default": 0.5
        },
        "crossfade": {
          "type": "boolean",
          "title": "Crossfade",
          "default": false
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "required": [
        "audio_urls"
      ],
      "title": "MergeAudioRequest",
      "description": "音频拼接请求"
    },
    "MixAudioRequest": {
      "properties": {
        "main_audio_url": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ],
          "title": "Main Audio Url"
        },
        "background_audio_url": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ],
          "title": "Background Audio Url"
        },
        "original_audio_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Original Audio Url"
        },
        "background_music_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Background Music Url"
        },
        "main_volume": {
          "type": "number",
          "maximum": 3.0,
          "minimum": 0.0,
          "title": "Main Volume",
          "default": 1.0
        },
        "background_volume": {
          "type": "number",
          "maximum": 3.0,
          "minimum": 0.0,
          "title": "Background Volume",
          "default": 0.3
        },
        "original_volume": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 3.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Original Volume"
        },
        "bgm_volume": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 3.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Bgm Volume"
        },
        "main_delay": {
          "type": "number",
          "minimum": 0.0,
          "title": "Main Delay",
          "default": 0.0
        },
        "original_delay": {
          "anyOf": [
            {
              "type": "number",
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Original Delay"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "title": "MixAudioRequest",
      "description": "混音请求（添加背景音乐）\n\n兼容前端历史字段名：original_audio_url / background_music_url 等。"
    },
    "SegmentConfig": {
      "properties": {
        "text": {
          "type": "string",
          "minLength": 1,
          "title": "Text",
          "description": "文本内容"
        },
        "voice_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Id",
          "description": "音色ID，为空则使用全局音色"
        },
        "speed": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.5,
          "title": "Speed",
          "description": "语速 (0.5-2.0)",
          "default": 1.0
        },
        "pitch": {
          "type": "number",
          "maximum": 12.0,
          "minimum": -12.0,
          "title": "Pitch",
          "description": "音调 (-12 ~ +12)",
          "default": 0.0
        },
        "pause_after": {
          "type": "number",
          "maximum": 5.0,
          "minimum": 0.0,
          "title": "Pause After",
          "description": "句后停顿(秒)",
          "default": 0.0
        },
        "emotion": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Emotion",
          "description": "情感: happy, sad, neutral, angry"
        }
      },
      "type": "object",
      "required": [
        "text"
      ],
      "title": "SegmentConfig",
      "description": "单句配置"
    },
    "SimpleTTSRequest": {
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text",
          "description": "要合成的文本"
        },
        "voice_id": {
          "type": "string",
          "title": "Voice Id",
          "description": "音色ID",
          "default": "xiaoxiao"
        },
        "speed": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.5,
          "title": "Speed",
          "description": "语速",
          "default": 1.0
        },
        "pitch": {
          "type": "number",
          "maximum": 12.0,
          "minimum": -12.0,
          "title": "Pitch",
          "description": "音调",
          "default": 0.0
        },
        "emotion": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Emotion",
          "description": "情感（qwen3）"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp3"
        },
        "engine": {
          "type": "string",
          "title": "Engine",
          "description": "edge | qwen3",
          "default": "edge"
        },
        "instruct": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Instruct",
          "description": "qwen3 指令"
        },
        "prompt_audio_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Audio Url",
          "description": "参考音频；有值时走 Qwen3 克隆合成"
        }
      },
      "type": "object",
      "required": [
        "text"
      ],
      "title": "SimpleTTSRequest",
      "description": "简单 TTS 请求（Edge / Qwen3）"
    },
    "SpeedRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "speed_factor": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.5,
          "title": "Speed Factor",
          "description": "速度倍数"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "speed_factor"
      ],
      "title": "SpeedRequest",
      "description": "变速请求"
    },
    "SplitAudioRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "segment_duration": {
          "type": "number",
          "maximum": 3600.0,
          "exclusiveMinimum": 0.0,
          "title": "Segment Duration",
          "description": "每段时长(秒)",
          "default": 30.0
        },
        "parts": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 100.0,
              "minimum": 2.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Parts",
          "description": "等分为 N 段（优先）"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        },
        "max_segments": {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 1.0,
          "title": "Max Segments",
          "default": 50
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "SplitAudioRequest",
      "description": "音频按时间分割请求"
    },
    "TTSRequest": {
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text"
        },
        "voice": {
          "type": "string",
          "title": "Voice",
          "description": "音色ID：Edge ShortName / 旧短 id / vivian 等 Qwen speaker / edge: 前缀",
          "default": "zh-CN-XiaoxiaoNeural"
        },
        "speed": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.5,
          "title": "Speed",
          "description": "语速 (0.5-2.0)",
          "default": 1.0
        },
        "pitch": {
          "type": "number",
          "maximum": 12.0,
          "minimum": -12.0,
          "title": "Pitch",
          "description": "音调 (-12 ~ +12)",
          "default": 0.0
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        },
        "engine": {
          "type": "string",
          "enum": [
            "edge",
            "qwen3"
          ],
          "title": "Engine",
          "description": "edge=云端 EdgeTTS; qwen3=本地（内置 speaker 或 Edge 示例克隆）",
          "default": "qwen3"
        },
        "emotion": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Emotion",
          "description": "qwen3 情感/风格"
        },
        "instruct": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Instruct",
          "description": "qwen3 指令"
        },
        "prompt_audio_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Audio Url",
          "description": "参考音频 URL；有值时强制 qwen3 克隆合成"
        },
        "prompt_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Text",
          "description": "参考音频对应文本；克隆合成时提升相似度"
        }
      },
      "type": "object",
      "required": [
        "text"
      ],
      "title": "TTSRequest",
      "description": "文字转语音请求（EdgeTTS / Qwen3-TTS / 示例音色克隆）"
    },
    "TranscribeRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "language": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Language",
          "description": "语言代码，None 为自动检测"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式: text, srt, vtt",
          "default": "text"
        },
        "with_align": {
          "type": "boolean",
          "title": "With Align",
          "description": "为 True 时在转写后调用 forced-align 生成词级时间戳（更慢）",
          "default": false
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "ASR 模型: auto=服务端默认尺寸(不按时长); qwen3=智能档(≤10min→1.7B, >10min→0.6B); qwen3-1.7b / qwen3-0.6b=强制指定"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "TranscribeRequest",
      "description": "语音转文字请求"
    },
    "TranscribeTaskRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "language": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Language"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "text"
        },
        "with_align": {
          "type": "boolean",
          "title": "With Align",
          "default": false
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "TranscribeTaskRequest"
    },
    "TrimAudioRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "start_time": {
          "type": "number",
          "minimum": 0.0,
          "title": "Start Time"
        },
        "end_time": {
          "type": "number",
          "exclusiveMinimum": 0.0,
          "title": "End Time"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "start_time",
        "end_time"
      ],
      "title": "TrimAudioRequest",
      "description": "音频裁剪请求"
    },
    "ValidationError": {
      "properties": {
        "loc": {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "type": "array",
          "title": "Location"
        },
        "msg": {
          "type": "string",
          "title": "Message"
        },
        "type": {
          "type": "string",
          "title": "Error Type"
        }
      },
      "type": "object",
      "required": [
        "loc",
        "msg",
        "type"
      ],
      "title": "ValidationError"
    },
    "VocalSeparateRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "strategy": {
          "type": "string",
          "title": "Strategy",
          "description": "分离策略: auto, demucs, spleeter",
          "default": "auto"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "VocalSeparateRequest",
      "description": "人声分离请求"
    },
    "VocalSeparateTaskRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "strategy": {
          "type": "string",
          "title": "Strategy",
          "default": "auto"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "default": "mp3"
        }
      },
      "type": "object",
      "required": [
        "audio_url"
      ],
      "title": "VocalSeparateTaskRequest"
    },
    "VoiceConvertRequest": {
      "properties": {
        "source_url": {
          "type": "string",
          "minLength": 1,
          "title": "Source Url",
          "description": "源说话音频 URL"
        },
        "reference_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reference Url",
          "description": "自定义目标音色参考音频 URL；与 preset_id 二选一"
        },
        "preset_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Preset Id",
          "description": "常用变声预设（Qwen3-TTS 合成参考音）"
        },
        "version": {
          "type": "string",
          "enum": [
            "v1",
            "v2"
          ],
          "title": "Version",
          "description": "Seed-VC 版本：v1=DiT；v2=CFM+AR（口音/情感）",
          "default": "v1"
        }
      },
      "type": "object",
      "required": [
        "source_url"
      ],
      "title": "VoiceConvertRequest",
      "description": "音频变声（Seed-VC）请求"
    },
    "VoiceConvertTaskRequest": {
      "properties": {
        "source_url": {
          "type": "string",
          "minLength": 1,
          "title": "Source Url"
        },
        "reference_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reference Url",
          "description": "自定义目标音色参考音频；与 preset_id 二选一"
        },
        "preset_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Preset Id",
          "description": "常用变声预设 id（Qwen3-TTS 合成参考音）"
        },
        "version": {
          "type": "string",
          "enum": [
            "v1",
            "v2"
          ],
          "title": "Version",
          "description": "Seed-VC 版本：v1=DiT；v2=CFM+AR",
          "default": "v1"
        }
      },
      "type": "object",
      "required": [
        "source_url"
      ],
      "title": "VoiceConvertTaskRequest",
      "description": "音频变声（Seed-VC）：参考音或预设音色。"
    },
    "VoiceDesignRequest": {
      "properties": {
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text",
          "description": "试听文案"
        },
        "instruct": {
          "type": "string",
          "maxLength": 1000,
          "minLength": 1,
          "title": "Instruct",
          "description": "音色自然语言描述，如：30岁成熟男声，低沉温和"
        },
        "language": {
          "type": "string",
          "title": "Language",
          "description": "合成语言",
          "default": "Chinese"
        },
        "voice_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Name",
          "description": "可选标签名"
        }
      },
      "type": "object",
      "required": [
        "text",
        "instruct"
      ],
      "title": "VoiceDesignRequest",
      "description": "自然语言音色设计试听（Qwen3 VoiceDesign）"
    },
    "VoiceDesignSaveRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url",
          "description": "设计试听音频 URL（作为克隆参考音）"
        },
        "prompt_text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Prompt Text",
          "description": "试听文案（与 audio_url 对齐，供后续 Base 克隆）"
        },
        "instruct": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 1000
            },
            {
              "type": "null"
            }
          ],
          "title": "Instruct",
          "description": "音色描述，写入元数据"
        },
        "voice_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Name",
          "description": "音色库名称"
        },
        "language": {
          "type": "string",
          "title": "Language",
          "description": "语言",
          "default": "Chinese"
        },
        "gender": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Gender",
          "description": "male / female，可选"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "prompt_text"
      ],
      "title": "VoiceDesignSaveRequest",
      "description": "将试听通过的设计音色写入「我的克隆」"
    },
    "VoiceEffectRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "effect": {
          "type": "string",
          "title": "Effect",
          "description": "效果类型: male, female, child, robot, echo"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "effect"
      ],
      "title": "VoiceEffectRequest",
      "description": "变声请求"
    },
    "VoiceoverSynthesizeRequest": {
      "properties": {
        "segments": {
          "items": {
            "$ref": "#/components/schemas/SegmentConfig"
          },
          "type": "array",
          "maxItems": 100,
          "minItems": 1,
          "title": "Segments",
          "description": "段落列表"
        },
        "global_voice_id": {
          "type": "string",
          "title": "Global Voice Id",
          "description": "全局默认音色",
          "default": "xiaoxiao"
        },
        "global_speed": {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.5,
          "title": "Global Speed",
          "description": "全局默认语速",
          "default": 1.0
        },
        "global_pitch": {
          "type": "number",
          "maximum": 12.0,
          "minimum": -12.0,
          "title": "Global Pitch",
          "description": "全局默认音调",
          "default": 0.0
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式: mp3, wav",
          "default": "mp3"
        },
        "merge_segments": {
          "type": "boolean",
          "title": "Merge Segments",
          "description": "是否合并为单个文件",
          "default": true
        }
      },
      "type": "object",
      "required": [
        "segments"
      ],
      "title": "VoiceoverSynthesizeRequest",
      "description": "配音合成请求（多段）"
    },
    "VolumeRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url"
        },
        "volume_factor": {
          "type": "number",
          "maximum": 3.0,
          "minimum": 0.0,
          "title": "Volume Factor",
          "description": "音量倍数，1.0为原始音量"
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "volume_factor"
      ],
      "title": "VolumeRequest",
      "description": "音量调整请求"
    },
    "src__api__v1__endpoints__audio__ai__VoiceCloneRequest": {
      "properties": {
        "audio_url": {
          "type": "string",
          "minLength": 1,
          "title": "Audio Url",
          "description": "参考音频 URL"
        },
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text",
          "description": "要用克隆音色合成的文本"
        },
        "voice_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Name",
          "description": "可选标签；写入音色库名称"
        },
        "prompt_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Text",
          "description": "参考音频对应文本"
        },
        "language": {
          "type": "string",
          "title": "Language",
          "description": "合成语言",
          "default": "Chinese"
        },
        "save_voice": {
          "type": "boolean",
          "title": "Save Voice",
          "description": "合成成功后是否保存到「我的克隆」音色库，供文字配音复用",
          "default": true
        }
      },
      "type": "object",
      "required": [
        "audio_url",
        "text"
      ],
      "title": "VoiceCloneRequest",
      "description": "音色克隆合成（Qwen3 即时克隆 + 写入可复用音色库）"
    },
    "src__api__v1__endpoints__audio__voiceover__VoiceCloneRequest": {
      "properties": {
        "voice_name": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 50,
              "minLength": 1
            },
            {
              "type": "null"
            }
          ],
          "title": "Voice Name",
          "description": "音色标签"
        },
        "audio_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Audio Url",
          "description": "参考音频URL"
        },
        "text": {
          "type": "string",
          "maxLength": 5000,
          "minLength": 1,
          "title": "Text",
          "description": "要用克隆音色合成的文本"
        },
        "prompt_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt Text",
          "description": "参考音频对应文本（可选）"
        },
        "language": {
          "type": "string",
          "title": "Language",
          "description": "合成语言",
          "default": "Chinese"
        },
        "save_voice": {
          "type": "boolean",
          "title": "Save Voice",
          "description": "是否保存到「我的克隆」音色库",
          "default": true
        }
      },
      "type": "object",
      "required": [
        "text"
      ],
      "title": "VoiceCloneRequest",
      "description": "音色克隆合成请求（Qwen3 即时克隆 + 写入可复用音色库）"
    }
  },
  "securitySchemes": {
    "HTTPBearer": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}
```