{
  "openapi": "3.0.1",
  "info": {
    "title": "FineVoice API",
    "description": "This is the documentation for the FineVoice API. If you have any questions or need assistance, please contact support@finevoice.ai.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://apis.finevoice.ai",
      "description": "FineVoice API Gateway"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/audio/speech-synthesis": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Text to Speech",
        "description": "Convert text into natural-sounding speech using a selected AI voice model.",
        "operationId": "SpeechSynthesis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextToSpeechRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/audio/voice-conversion": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Voice Conversion",
        "description": "Transform the voice in an audio file to a different AI voice while preserving the original content.",
        "operationId": "VoiceConversion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoiceConversionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/audio/stt": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Speech to Text",
        "description": "Transcribe speech from an audio or video URL into text, with optional speaker diarization and word-level timestamps.",
        "operationId": "SpeechToText",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechToTextRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/audio/sfx-generation": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Sound Effect Generation",
        "description": "Generate royalty-free sound effects from a text prompt or a source video/image.",
        "operationId": "SfxGeneration",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SoundEffectGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/audio/separation": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Audio Separation",
        "description": "Separate vocals, instruments, and other audio stems from an audio file using AI.",
        "operationId": "AudioSeparation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeparationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/audio/podcastgen": {
      "post": {
        "tags": [
          "Audio"
        ],
        "summary": "Podcast Generation",
        "description": "Generate a multi-speaker AI podcast from a script or prompt, with selectable voice models for each speaker.",
        "operationId": "PodcastGen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PodcastGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted. Returns a taskId for async polling or the result URL directly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/voice/train": {
      "post": {
        "tags": [
          "Voice"
        ],
        "summary": "Train Voice Model",
        "description": "Create a custom AI voice model by providing a training audio URL and basic profile information.",
        "operationId": "TrainVoice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoiceTrainRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Training task accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/voice/design": {
      "post": {
        "tags": [
          "Voice"
        ],
        "summary": "Voice Design",
        "description": "Design a new AI voice from a text prompt and preview it with sample text.",
        "operationId": "VoiceDesign",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoiceDesignRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Voice design task accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/voice/{name}": {
      "get": {
        "tags": [
          "Voice"
        ],
        "summary": "Get Voice Detail",
        "description": "Retrieve detailed information about a specific voice model by its name.",
        "operationId": "GetVoiceDetail",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The voice model name.",
            "example": "james"
          },
          {
            "name": "desigUuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional design UUID to retrieve a specific voice design version."
          }
        ],
        "responses": {
          "200": {
            "description": "Voice detail returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "404": {
            "description": "Voice not found."
          }
        }
      }
    },
    "/v1/voice/pagevoices": {
      "get": {
        "tags": [
          "Voice"
        ],
        "summary": "List Voice Models",
        "description": "Retrieve a paginated, filterable list of available AI voice models.",
        "operationId": "PageVoices",
        "parameters": [
          {
            "name": "categroy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "my_voices",
                "favorite"
              ],
              "example": "all"
            },
            "description": "Category filter. `all` returns every voice, `my_voices` returns custom models, `favorite` returns favorited voices."
          },
          {
            "name": "primary_category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "social-media",
                "advertisement",
                "characters-and-animation",
                "entertainment-and-tv",
                "informative-and-educational",
                "narrative-and-story",
                "interactive_media",
                "healthcare",
                "companions",
                "education_training",
                "enterprise",
                "all"
              ],
              "example": "all"
            },
            "description": "Primary category filter."
          },
          {
            "name": "gender",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by gender (e.g. `male`, `female`)."
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "en-US"
            },
            "description": "Language filter using locale codes such as `en-US`, `zh-CN`, `ja-JP`."
          },
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Search keyword to filter voice names."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0,
              "example": 0
            },
            "description": "Page index, starting from 0."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "description": "Number of voices per page."
          },
          {
            "name": "tts",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Filter for TTS-compatible voices only."
          },
          {
            "name": "style",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by voice style."
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by age range."
          },
          {
            "name": "sub_category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Sub-category filter."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of voice models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          }
        }
      }
    },
    "/v1/task/{task_id}": {
      "get": {
        "tags": [
          "Task"
        ],
        "summary": "Get Task Status",
        "description": "Poll the status and result of an asynchronous audio processing task.",
        "operationId": "GetTaskStatus",
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The task identifier returned by a previous API call.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status and result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskQueryResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "404": {
            "description": "Task not found."
          }
        }
      }
    },
    "/v1/music/musicgenbyprompt": {
      "post": {
        "tags": [
          "Music"
        ],
        "summary": "Music Generation by Prompt",
        "description": "Generate a royalty-free music track from a text prompt, with control over style, duration, and model version.",
        "operationId": "MusicGenByPrompt",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MusicGenerationByPromptRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/music/musicgen": {
      "post": {
        "tags": [
          "Music"
        ],
        "summary": "Music Generation by Lyrics",
        "description": "Generate a full music track with vocals and/or instrumentation from lyrics, style description, and reference tracks.",
        "operationId": "MusicGen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MusicGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/music/cover": {
      "post": {
        "tags": [
          "Music"
        ],
        "summary": "Music Cover",
        "description": "Create an AI voice cover of a song by replacing the original vocals with a target AI voice model.",
        "operationId": "MusicCover",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MusicCoverRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/speech_enhancement": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Speech Enhancement",
        "description": "Reduce background noise and enhance speech quality. Supports WAV/MP3/FLAC/AAC/OGG/OPUS/M4A/WEBM. Returns enhanced audio file.",
        "operationId": "SpeechEnhancement",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechEnhancementRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enhanced audio returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/speech_super_resolution": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Speech Super Resolution",
        "description": "Upsample low-quality audio from 8 kHz to 48 kHz using the MossFormer2_SR_48K model. Returns high sample-rate audio file.",
        "operationId": "SpeechSuperResolution",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechSuperResolutionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "High sample-rate audio returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/speech_separation": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Speech Separation",
        "description": "Separate two speakers from a mixed audio file using the MossFormer2_SS_16K model. Use `speaker_index` (0 or 1) to select which speaker to return.",
        "operationId": "EnhancerSpeechSeparation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechSeparationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Separated speaker audio returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/remove_mouth_sounds": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Remove Mouth Sounds",
        "description": "Remove mouth sounds (clicks, pops, breathing) from audio using RNNoise, Hush, or Whisper-based stutter detection.",
        "operationId": "RemoveMouthSounds",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveMouthSoundsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/remove_long_silences": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Remove Long Silences",
        "description": "Detect and trim silence segments exceeding a threshold duration while preserving boundary silence to avoid abrupt cuts.",
        "operationId": "RemoveLongSilences",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveLongSilencesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/filler_words/detect": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Filler Words Detect",
        "description": "Detect filler words (um, uh, er, hmm) in audio. Default mode uses a lightweight audio classifier (language-agnostic). Whisper mode uses ASR for precise word-level timestamps.",
        "operationId": "FillerWordsDetect",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FillerWordsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Filler word timestamps returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/filler_words/remove": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Filler Words Remove",
        "description": "Detect and remove filler words from audio. Default mode uses an audio classifier; Whisper mode uses ASR to precisely locate and cut filler words.",
        "operationId": "FillerWordsRemove",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FillerWordsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio file returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/stuttering/remove": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Stuttering Remove",
        "description": "Detect and remove stuttering segments from audio using Whisper ASR. Returns processed audio file.",
        "operationId": "StutteringRemove",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StutteringRemoveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio file returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/audio_normalization": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Audio Normalization",
        "description": "Normalize audio loudness using peak, RMS, or combined normalization methods. Returns normalized audio file.",
        "operationId": "AudioNormalization",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AudioNormalizationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized audio file returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    },
    "/v1/enhancer/process/pipeline": {
      "post": {
        "tags": [
          "Audio Enhancer"
        ],
        "summary": "Process Pipeline",
        "description": "All-in-one audio processing pipeline. Select steps via boolean flags. Execution order: (1) Speech Enhancement, (2) Remove Mouth Sounds, (3) Remove Long Silences, (4) Super Resolution, (5) Filler Words Removal, (6) Stuttering Removal, (7) Audio Normalization. Returns a download URL.",
        "operationId": "ProcessPipeline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio download URL returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — invalid or missing API key."
          },
          "422": {
            "description": "Validation error — check request body fields."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token (API key). Format: `Bearer {your_api_key}`"
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "description": "Error message."
          }
        }
      },
      "AudioTaskResponse": {
        "type": "object",
        "description": "Standard response for audio processing tasks.",
        "properties": {
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP-style status code (200 for success, 202 for in-progress)."
          },
          "url": {
            "type": "string",
            "description": "Download URL of the generated audio file (available when completed)."
          },
          "taskId": {
            "type": "string",
            "description": "Task identifier for async polling. Use with GET /v1/task/{task_id}.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "error": {
            "$ref": "#/components/schemas/ApiError"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Multiple output URLs (e.g. for separation stems)."
          },
          "service": {
            "type": "string"
          },
          "port": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          }
        }
      },
      "TaskQueryResponse": {
        "type": "object",
        "description": "Response for task status polling.",
        "properties": {
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP-style status code (200 for completed, 202 for in-progress)."
          },
          "url": {
            "type": "string",
            "description": "Download URL of the result.",
            "example": "https://cdn.finevoice.ai/output/result.mp3"
          },
          "taskId": {
            "type": "string",
            "description": "Task identifier.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "error": {
            "$ref": "#/components/schemas/ApiError"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Multiple output URLs."
          },
          "service": {
            "type": "string"
          },
          "port": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          }
        }
      },
      "TextToSpeechRequest": {
        "type": "object",
        "description": "The text-to-speech request payload.",
        "properties": {
          "voice": {
            "type": "string",
            "description": "The target voice model name. Retrieve available voices from the List AI Voices API.",
            "example": "james"
          },
          "text": {
            "type": "string",
            "description": "The text content to synthesize. Supports emotion tags such as `[happy]`, `[sad]`, `[breathe]`.",
            "example": "[happy] Hello! Welcome to FineVoice."
          }
        }
      },
      "VoiceConversionRequest": {
        "type": "object",
        "description": "The voice conversion request payload.",
        "properties": {
          "voice": {
            "type": "string",
            "description": "The target voice model name.",
            "example": "leo"
          },
          "sourceUrl": {
            "type": "string",
            "description": "The source audio URL.",
            "example": "https://dlaudio.fineshare.net/cover/speak/30f23d17-634d-420e-99e7-d24097dc669b.mp3"
          },
          "outputFormat": {
            "type": "string",
            "description": "The desired output audio format. Supported: `mp3`, `wav`.",
            "example": "mp3"
          },
          "useAsync": {
            "type": "boolean",
            "description": "Set to `true` to process asynchronously and receive a `taskId` for polling.",
            "example": true
          }
        }
      },
      "SpeechToTextRequest": {
        "type": "object",
        "description": "The speech-to-text request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "The source audio or video URL.",
            "example": "https://example.com/audio.mp3"
          },
          "language": {
            "type": "string",
            "description": "The source language code (e.g. `en`, `zh`, `ja`).",
            "example": "en"
          },
          "title": {
            "type": "string",
            "description": "An optional task title for reference."
          },
          "format": {
            "type": "string",
            "description": "Expected transcript output format: `srt`, `vtt`, `json`, `txt`.",
            "example": "json"
          },
          "engine": {
            "type": "string",
            "description": "The transcription engine to use. Supported: `whisper`, `funasr`.",
            "example": "whisper"
          },
          "useAsync": {
            "type": "boolean",
            "description": "Set to `true` to process asynchronously.",
            "example": true
          },
          "word_level_timestamp_alignment": {
            "type": "boolean",
            "description": "Whether to include word-level timestamp alignment.",
            "example": false
          },
          "speaker_diarization": {
            "type": "boolean",
            "description": "Whether to enable speaker diarization (identify multiple speakers).",
            "example": false
          },
          "min_speakers": {
            "type": "integer",
            "format": "int32",
            "description": "Minimum number of speakers for diarization."
          },
          "max_speakers": {
            "type": "integer",
            "format": "int32",
            "description": "Maximum number of speakers for diarization."
          },
          "batch_size": {
            "type": "integer",
            "format": "int32",
            "description": "The transcription batch size."
          },
          "script_target": {
            "type": "string",
            "description": "The target output script style or format."
          }
        }
      },
      "SoundEffectGenerationRequest": {
        "type": "object",
        "description": "The sound effect generation request payload.",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The prompt describing the desired sound effect.",
            "example": "Thunderstorm with heavy rain and distant thunder"
          },
          "negative_prompt": {
            "type": "string",
            "description": "The negative prompt describing sounds to avoid.",
            "example": "music, voices"
          },
          "sourceUrl": {
            "type": "string",
            "description": "Source video or image URL for generating contextual sound effects. If provided, `sourceType` is required."
          },
          "sourceType": {
            "type": "string",
            "description": "The source media type. Supported: `image`, `video`. Required when `sourceUrl` is provided.",
            "example": "video"
          },
          "duration": {
            "type": "number",
            "format": "float",
            "description": "Requested output duration in seconds. Maximum is 30 seconds.",
            "example": 5.0
          },
          "useAsync": {
            "type": "boolean",
            "description": "Set to `true` to process asynchronously.",
            "example": true
          }
        }
      },
      "SeparationRequest": {
        "type": "object",
        "description": "The audio separation request payload.",
        "properties": {
          "sourceUrl": {
            "type": "string",
            "description": "The source audio URL.",
            "example": "https://webresources.fineshare.net/finevoice3/audio/isolator-original.mp3"
          },
          "model": {
            "type": "string",
            "description": "The separation model. Supported: `vocal-remover`, `htdemucs_6s-4`, `reverb`.",
            "example": "vocal-remover"
          },
          "useAsync": {
            "type": "boolean",
            "description": "Set to `true` to process asynchronously.",
            "example": true
          }
        }
      },
      "PodcastGenerationRequest": {
        "type": "object",
        "description": "The podcast generation request payload.",
        "properties": {
          "text": {
            "type": "string",
            "description": "The podcast script content.",
            "example": "Welcome to the FineVoice podcast. Today we discuss AI audio..."
          },
          "thumbnail": {
            "type": "string",
            "description": "The thumbnail image URL."
          },
          "speakers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Voice models used by podcast speakers.",
            "example": [
              "olivia",
              "ethan"
            ]
          },
          "expectedDuration": {
            "type": "string",
            "description": "The expected generated duration.",
            "example": "5min"
          },
          "prompt": {
            "type": "string",
            "description": "The generation prompt."
          },
          "style": {
            "type": "string",
            "description": "The desired podcast style.",
            "example": "conversational"
          },
          "originalText": {
            "type": "boolean",
            "description": "Whether to keep the original text wording."
          },
          "useAsync": {
            "type": "boolean",
            "description": "Set to `true` to process asynchronously.",
            "example": true
          }
        }
      },
      "VoiceTrainRequest": {
        "type": "object",
        "description": "The voice training request payload.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The display name of the trained model.",
            "example": "My Custom Voice"
          },
          "languageCode": {
            "type": "string",
            "description": "The language code of the training audio.",
            "example": "en-US"
          },
          "gender": {
            "type": "string",
            "description": "The target voice gender.",
            "example": "female"
          },
          "audioUrl": {
            "type": "string",
            "description": "The remote audio URL used for training.",
            "example": "https://example.com/training_audio.wav"
          },
          "imageUrl": {
            "type": "string",
            "description": "The remote avatar image URL."
          }
        }
      },
      "VoiceDesignRequest": {
        "type": "object",
        "description": "The voice design request payload.",
        "properties": {
          "taskId": {
            "type": "string",
            "description": "Task identifier for updating an existing design task."
          },
          "engine": {
            "type": "string",
            "description": "Voice generation engine. Supported: `v1`, `v2`.",
            "example": "v2"
          },
          "prompt": {
            "type": "string",
            "description": "Voice design prompt describing desired voice characteristics.",
            "example": "A warm, friendly female voice with a slight British accent"
          },
          "previewText": {
            "type": "string",
            "description": "Preview text used to audition the designed voice.",
            "example": "Hello, this is a preview of the designed voice."
          },
          "modelId": {
            "type": "string",
            "description": "The base model identifier."
          },
          "seed": {
            "type": "integer",
            "format": "int64",
            "description": "Random seed for deterministic generation."
          }
        }
      },
      "MusicGenerationByPromptRequest": {
        "type": "object",
        "description": "The prompt-based music generation request payload.",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The generation prompt describing the desired music.",
            "example": "Upbeat electronic dance music with heavy bass and synth leads"
          },
          "instrumental": {
            "type": "boolean",
            "description": "Whether to generate instrumental-only music (no vocals).",
            "example": true
          },
          "duration": {
            "type": "integer",
            "format": "int32",
            "description": "The target duration in seconds.",
            "example": 30
          },
          "continuation": {
            "type": "boolean",
            "description": "Whether this generation continues a previous clip."
          },
          "title": {
            "type": "string",
            "description": "The generated song title."
          },
          "modelVersion": {
            "type": "string",
            "description": "The model version to use."
          },
          "audioId": {
            "type": "string",
            "description": "Source audio identifier for continuation or reference."
          },
          "prompt_type": {
            "type": "string",
            "description": "The prompt input type."
          },
          "input_audio": {
            "type": "string",
            "description": "Optional input audio reference URL."
          },
          "thumbnail_url": {
            "type": "string",
            "description": "The thumbnail image URL."
          }
        }
      },
      "MusicGenerationRequest": {
        "type": "object",
        "description": "The music generation request payload.",
        "properties": {
          "title": {
            "type": "string",
            "description": "The generated song title.",
            "example": "My AI Song"
          },
          "style": {
            "type": "string",
            "description": "The target music style.",
            "example": "pop, energetic, upbeat"
          },
          "audioId": {
            "type": "string",
            "description": "The source audio identifier."
          },
          "referVoice": {
            "type": "string",
            "description": "Reference vocal track identifier or URL."
          },
          "referInstrumental": {
            "type": "string",
            "description": "Reference instrumental track identifier or URL."
          },
          "lyrics": {
            "type": "string",
            "description": "The lyrics content.",
            "example": "[Verse 1]\nHello world, this is FineVoice..."
          },
          "instrumental": {
            "type": "boolean",
            "description": "Whether to generate instrumental-only music.",
            "example": false
          },
          "modelVersion": {
            "type": "string",
            "description": "Model version. `v3`: optimized for Chinese vocals and traditional styles. `r2`: studio recording quality with highly realistic vocals.",
            "example": "v3",
            "enum": [
              "v3",
              "r2"
            ]
          }
        }
      },
      "MusicCoverRequest": {
        "type": "object",
        "description": "The music cover request payload.",
        "properties": {
          "voice": {
            "type": "string",
            "description": "The primary target voice model name.",
            "example": "james"
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "minimum": -12,
            "maximum": 12,
            "description": "Vocal pitch offset in semitones.",
            "example": 0,
            "default": 0
          },
          "outputFormat": {
            "type": "string",
            "description": "The desired output format.",
            "example": "mp3"
          },
          "audioName": {
            "type": "string",
            "description": "The output audio name."
          },
          "audioCover": {
            "type": "string",
            "description": "The cover image URL."
          },
          "way": {
            "type": "string",
            "description": "Processing mode. Must be `m2`.",
            "example": "m2"
          },
          "cut": {
            "type": "integer",
            "format": "int32",
            "description": "The cut mode."
          },
          "engine": {
            "type": "string",
            "description": "Voice conversion engine. `v5`: great for singing (rich vibrato, more noise). `v7`: great for speech (clean, stable).",
            "example": "v5",
            "enum": [
              "v5",
              "v7"
            ]
          },
          "sourceUrl": {
            "type": "string",
            "description": "The source audio URL.",
            "example": "https://example.com/song.mp3"
          },
          "singers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MusicCoverSingerRequest"
            },
            "description": "Singer configurations for a multi-singer cover."
          },
          "instrument_pitch": {
            "type": "number",
            "format": "float",
            "description": "Instrumental pitch offset in semitones."
          },
          "pitch_control": {
            "type": "string",
            "description": "Pitch control mode. Must be `rmvpe`.",
            "example": "rmvpe"
          },
          "diffusion_steps": {
            "type": "integer",
            "format": "int32",
            "description": "Number of diffusion steps."
          },
          "auto_f0_adjust": {
            "type": "boolean",
            "description": "Whether to enable automatic F0 adjustment."
          },
          "vocal_types": {
            "type": "string",
            "description": "Vocal type configuration.",
            "example": "solo",
            "default": "solo",
            "enum": [
              "solo",
              "chorus",
              "duets"
            ]
          }
        }
      },
      "MusicCoverSingerRequest": {
        "type": "object",
        "description": "A singer configuration for a multi-singer music cover task.",
        "properties": {
          "voice": {
            "type": "string",
            "description": "The singer voice model name.",
            "example": "james"
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "description": "Pitch offset for this singer in semitones."
          },
          "engine": {
            "type": "string",
            "description": "Voice conversion engine. `v5`: great for singing. `v7`: great for speech.",
            "example": "v5",
            "enum": [
              "v5",
              "v7"
            ]
          },
          "diffusion_steps": {
            "type": "integer",
            "format": "int32",
            "description": "Number of diffusion steps."
          },
          "auto_f0_adjust": {
            "type": "boolean",
            "description": "Whether to enable automatic F0 adjustment."
          }
        }
      },
      "SpeechEnhancementRequest": {
        "type": "object",
        "description": "The speech enhancement request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio file URL (http/https). Supports WAV/MP3/FLAC/AAC/OGG/OPUS/M4A/WEBM.",
            "example": "https://example.com/audio.mp3"
          },
          "model": {
            "type": "string",
            "description": "Enhancement model. Supported: `MossFormer2_SE_48K`, `FRCRN_SE_16K`, `MossFormerGAN_SE_16K`.",
            "example": "MossFormer2_SE_48K",
            "default": "MossFormer2_SE_48K"
          },
          "use_vad": {
            "type": "boolean",
            "description": "Enable VAD (Voice Activity Detection) preprocessing.",
            "default": false
          },
          "enable_normalization": {
            "type": "boolean",
            "description": "Enable audio normalization after enhancement.",
            "default": false
          },
          "normalization_method": {
            "type": "string",
            "description": "Normalization method: `peak`, `rms`, or `both`.",
            "default": "peak"
          },
          "normalization_peak_db": {
            "type": "number",
            "description": "Target peak level in dBFS.",
            "default": -1.0
          },
          "normalization_rms_db": {
            "type": "number",
            "description": "Target RMS level in dBFS.",
            "default": -20.0
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "SpeechSuperResolutionRequest": {
        "type": "object",
        "description": "The speech super resolution request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Low sample-rate audio URL (http/https).",
            "example": "https://example.com/low_quality.mp3"
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "SpeechSeparationRequest": {
        "type": "object",
        "description": "The speech separation request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Mixed-speech audio URL (http/https).",
            "example": "https://example.com/mixed_speakers.mp3"
          },
          "speaker_index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1,
            "description": "Which speaker to return: `0` or `1`.",
            "default": 0
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "RemoveMouthSoundsRequest": {
        "type": "object",
        "description": "The remove mouth sounds request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "use_rnnoise": {
            "type": "boolean",
            "description": "Enable RNNoise broadband denoising.",
            "default": false
          },
          "rnnoise_strength": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "RNNoise strength (0–100).",
            "default": 80
          },
          "use_hush": {
            "type": "boolean",
            "description": "Enable Hush background voice suppression.",
            "default": false
          },
          "hush_atten_lim_db": {
            "type": "number",
            "description": "Hush attenuation limit in dB.",
            "default": 60.0
          },
          "use_whisper_stutter": {
            "type": "boolean",
            "description": "Also remove stuttering using Whisper.",
            "default": false
          },
          "whisper_model_size": {
            "type": "string",
            "description": "Whisper model size: `tiny`, `base`, `small`, or `medium`.",
            "default": "base"
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "RemoveLongSilencesRequest": {
        "type": "object",
        "description": "The remove long silences request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "silence_threshold_db": {
            "type": "number",
            "description": "Silence detection threshold in dBFS.",
            "default": -42.0
          },
          "long_silence_ms": {
            "type": "integer",
            "description": "Silences longer than this value (ms) are trimmed.",
            "default": 1200
          },
          "keep_silence_ms": {
            "type": "integer",
            "description": "Silence padding to preserve at boundaries (ms).",
            "default": 180
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "FillerWordsRequest": {
        "type": "object",
        "description": "The filler words detect/remove request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          },
          "use_whisper": {
            "type": "boolean",
            "description": "Use Whisper ASR for accurate, language-aware filler word detection.",
            "default": false
          },
          "whisper_model_size": {
            "type": "string",
            "description": "Whisper model size: `tiny`, `base`, `small`, or `medium`. Used when `use_whisper` is `true`.",
            "default": "base"
          },
          "language": {
            "type": "string",
            "description": "Language code for Whisper (e.g. `en`, `zh`, `ja`, `fr`). Used when `use_whisper` is `true`.",
            "default": "en"
          },
          "filler_words_list": {
            "type": "string",
            "description": "Comma-separated filler words to detect/remove. Empty = built-in defaults.",
            "default": "um,uh,er,hmm,hm,ah,eh,mhm"
          }
        }
      },
      "StutteringRemoveRequest": {
        "type": "object",
        "description": "The stuttering removal request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "whisper_model_size": {
            "type": "string",
            "description": "Whisper model size for stutter detection: `tiny`, `base`, `small`, or `medium`.",
            "default": "base"
          },
          "min_similarity": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 1.0,
            "description": "Minimum similarity threshold for stutter detection.",
            "default": 0.75
          },
          "max_gap_ms": {
            "type": "number",
            "minimum": 0.0,
            "description": "Maximum gap between stutter repetitions in ms.",
            "default": 500.0
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "AudioNormalizationRequest": {
        "type": "object",
        "description": "The audio normalization request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "method": {
            "type": "string",
            "description": "Normalization method: `peak` (prevents clipping), `rms` (uniform volume), or `both` (RMS first, then peak).",
            "default": "peak"
          },
          "peak_db": {
            "type": "number",
            "description": "Target peak level in dBFS.",
            "default": -1.0
          },
          "rms_db": {
            "type": "number",
            "description": "Target RMS level in dBFS.",
            "default": -20.0
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      },
      "PipelineRequest": {
        "type": "object",
        "description": "The all-in-one audio processing pipeline request payload.",
        "properties": {
          "url": {
            "type": "string",
            "description": "Audio file URL (http/https).",
            "example": "https://example.com/audio.mp3"
          },
          "step_speech_enhancement": {
            "type": "boolean",
            "description": "Enable Speech Enhancement step (noise reduction).",
            "default": true
          },
          "step_remove_mouth_sounds": {
            "type": "boolean",
            "description": "Enable Remove Mouth Sounds step.",
            "default": false
          },
          "step_remove_long_silences": {
            "type": "boolean",
            "description": "Enable Remove Long Silences step.",
            "default": false
          },
          "step_super_resolution": {
            "type": "boolean",
            "description": "Enable Super Resolution step (8 kHz to 48 kHz).",
            "default": false
          },
          "step_filler_words_remove": {
            "type": "boolean",
            "description": "Enable Filler Words Removal step.",
            "default": false
          },
          "step_stuttering_remove": {
            "type": "boolean",
            "description": "Enable Stuttering Removal step.",
            "default": false
          },
          "step_audio_normalization": {
            "type": "boolean",
            "description": "Enable Audio Normalization step.",
            "default": false
          },
          "enhancement_model": {
            "type": "string",
            "description": "Speech enhancement model: `MossFormer2_SE_48K`, `FRCRN_SE_16K`, or `MossFormerGAN_SE_16K`.",
            "default": "FRCRN_SE_16K"
          },
          "enhancement_use_vad": {
            "type": "boolean",
            "description": "Enable VAD preprocessing for speech enhancement.",
            "default": false
          },
          "silence_threshold_db": {
            "type": "number",
            "description": "Silence detection threshold in dBFS.",
            "default": -42.0
          },
          "long_silence_ms": {
            "type": "integer",
            "description": "Silences longer than this value (ms) are trimmed.",
            "default": 1200
          },
          "keep_silence_ms": {
            "type": "integer",
            "description": "Silence padding to preserve at boundaries (ms).",
            "default": 180
          },
          "filler_use_whisper": {
            "type": "boolean",
            "description": "Use Whisper for filler word detection.",
            "default": false
          },
          "filler_language": {
            "type": "string",
            "description": "Language code for filler word detection (e.g. `en`, `zh`).",
            "default": "en"
          },
          "filler_words_list": {
            "type": "string",
            "description": "Comma-separated filler words to remove. Empty = built-in defaults.",
            "default": "um,uh,er,hmm,hm,ah,eh,mhm"
          },
          "stutter_min_similarity": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 1.0,
            "description": "Minimum similarity for stutter detection.",
            "default": 0.75
          },
          "norm_method": {
            "type": "string",
            "description": "Normalization method: `peak`, `rms`, or `both`.",
            "default": "peak"
          },
          "norm_peak_db": {
            "type": "number",
            "description": "Target peak level in dBFS.",
            "default": -1.0
          },
          "norm_rms_db": {
            "type": "number",
            "description": "Target RMS level in dBFS.",
            "default": -20.0
          },
          "output_format": {
            "type": "string",
            "description": "Output format: `wav`, `mp3`, `flac`, or `m4a`.",
            "default": "wav"
          }
        }
      }
    }
  }
}