xiaoxia-saas/apps/api/app/schemas/voice_clone.py

"""音色克隆 API Schema。"""

from __future__ import annotations

from datetime import datetime
from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field


class CreateVoiceCloneRequest(BaseModel):
    """创建音色克隆请求。"""

    name: str = Field(..., min_length=1, max_length=100, description="音色名称")
    description: str = Field("", description="音色描述")
    source_audio_url: str = Field("", description="参考音频 URL（与 asset_id 二选一）")
    asset_id: str = Field("", description="参考音频素材 ID（配音素材库中的音频 asset，与 source_audio_url 二选一）")
    voice_model: str = Field("", description="语音模型名称")
    language: str = Field("zh-CN", description="语言")
    gender: str = Field("unknown", description="性别")
    max_retries: int = Field(3, ge=1, le=10, description="最大重试次数")
    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")

    class Config:
        populate_by_name = True


class VoiceCloneProfileResponse(BaseModel):
    """音色克隆档案响应。"""

    id: str
    user_id: str
    name: str
    description: str = ""
    source_audio_url: str = ""
    voice_id: str = ""
    voice_model: str = ""
    language: str = "zh-CN"
    gender: str = "unknown"
    status: str
    error_message: str = ""
    retry_count: int = 0
    max_retries: int = 3
    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")
    created_at: datetime
    updated_at: datetime

    class Config:
        populate_by_name = True


class VoiceCloneStatusResponse(BaseModel):
    """音色克隆状态响应（用于轮询）。"""

    id: str
    status: str
    error_message: str = ""
    voice_id: str = ""
    retry_count: int = 0


class ListVoiceCloneResponse(BaseModel):
    """音色克隆列表响应。"""

    items: List[VoiceCloneProfileResponse]
    total: int


class VoiceClonePreviewResponse(BaseModel):
    """克隆音色试听响应。"""

    clone_id: str
    """音色克隆档案 ID"""

    voice_id: str
    """CosyVoice 音色 ID"""

    audio_url: str
    """试听音频 URL"""

    text: str
    """试听文本"""

    duration: float = 0.0
    """音频时长（秒）"""

    file_size: int = 0
    """文件大小（字节）"""