qqmusic-api-python 0.6.7__tar.gz → 0.6.9__tar.gz

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/.dockerignore

@@ -22,5 +22,3 @@ dist
 .prek_cache
 *.toml
 !pyproject.toml
-!web/config.toml
-!web/accounts.toml

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/.gitignore

@@ -13,6 +13,7 @@ device.json
 # AI
 .ccb/
 docs/superpowers/
+.omo/
 
 # Distribution / packaging
 .Python

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/AGENTS.md

@@ -47,6 +47,27 @@
 * 新增页面必须同步更新 `zensical.toml` 的 `nav`。
 * 文档构建工具实际使用 `zensical`，配置文件是 `zensical.toml`。
 
+## Release workflow
+
+1. 更新 `qqmusic_api/__init__.py` 中的 `__version__` 为待发布版本。
+2. 提交版本号变更：
+
+   ```bash
+   git add qqmusic_api/__init__.py
+   git commit -m "🧹 chore(release): x.x.x"
+   ```
+
+3. 在**该提交上**打 tag 并推送：
+
+   ```bash
+   git tag v0.x.x
+   git push origin v0.x.x
+   ```
+
+4. CI 自动执行：
+   * **release.yml**：`uv build` → `uv publish`（PyPI）→ 创建 GitHub Release（git-cliff 自动生成 release body）
+   * **docs.yml**（release published 后触发）：更新 `docs/release-notes.md` → 导出 `web/requirements.txt` → commit → 构建文档站 → 部署 GitHub Pages
+
 ## Agent behavior
 
 * **核心规约**：遵循 `docs/contributing.md` 中的详细规约。**在执行任务前，必须完整阅读该指南以确保合规。**

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.7
+Version: 0.6.9
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/
@@ -37,6 +37,8 @@ Requires-Dist: paho-mqtt>=2.1.0
 Requires-Dist: pydantic>=2.13.3
 Requires-Dist: tarsio>=0.5.1
 Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: upload
+Requires-Dist: cos-python-sdk-v5>=1.9.44; extra == 'upload'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -56,6 +58,9 @@ Description-Content-Type: text/markdown
     <a href="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml">
         <img src="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing">
     </a>
+    <a href="https://deepwiki.com/luren-dc/QQMusicApi">
+        <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+    </a>
 </div>
 
 ---

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/README.md

@@ -15,6 +15,9 @@
     <a href="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml">
         <img src="https://github.com/l-1124/QQMusicApi/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing">
     </a>
+    <a href="https://deepwiki.com/luren-dc/QQMusicApi">
+        <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+    </a>
 </div>
 
 ---

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/docs/coding.md

@@ -221,21 +221,24 @@ class Singer(Response):
 
 ### 需登录的接口
 
-需要登录的接口应通过 `_require_login` 校验凭证：
+需要登录的接口通过 `_build_request` 的 `require_login` 参数校验凭证：
 
 ```python
 def get_vip_info(self, *, credential: Credential | None = None):
     """获取 VIP 信息."""
-    target_credential = self._require_login(credential)
     return self._build_request(
         module="VipLogin.VipLoginInter",
         method="vip_login_base",
         param={},
-        credential=target_credential,
+        credential=credential,
         response_model=UserVipInfoResponse,
+        require_login=True,
     )
 ```
 
+> 若接口需要凭证对象的字段来构建请求参数，
+> 仍可显式调用 `_require_login` 获取凭证对象。
+
 ## 翻页与换一批
 
 ### 连续翻页

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/docs/release-notes.md

@@ -1,18 +1,64 @@
 
-## What's Changed
+## [[0.6.8](https://github.com/L-1124/QQMusicApi/compare/v0.6.7..v0.6.8)] - 2026-07-01
+
+### Bug 修复
+
+* **(web)** 禁用 FastAPI 默认按别名响应，使 JSON 输出与 Python 原生变量名保持一致 ([32459a5](https://github.com/L-1124/QQMusicApi/commit/32459a54c03d8a0a738f1917f9eb19fc6f9ac4ef)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 新增 SignatureRequiredError 错误码 2000 处理 ([a73313a](https://github.com/L-1124/QQMusicApi/commit/a73313a91549a156358ad9311d0e20d7401b861b)) by [@L-1124](https://github.com/L-1124)
+* **(core)** _ensure_session 添加 24h 保活机制 ([2290a32](https://github.com/L-1124/QQMusicApi/commit/2290a32304bcd9052365f60c67f2d4f6b00e4d7e)) by [@L-1124](https://github.com/L-1124)
+* **(helper)** 新增辅助功能接口 ([eb0c40c](https://github.com/L-1124/QQMusicApi/commit/eb0c40c1461826955a1eb005afb723438730142a)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 支持登出API ([73f2a7e](https://github.com/L-1124/QQMusicApi/commit/73f2a7ee9ad1d48cbec2d6aa9dbf844f44b573c2)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 彻底移除 crypt 字段，隐式处理加密状态 ([80edc40](https://github.com/L-1124/QQMusicApi/commit/80edc40e41331f6b5c11146d5daf6eccf344181f)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 移除 decrypt 方法，改为默认解密 ([24949c4](https://github.com/L-1124/QQMusicApi/commit/24949c4df8c63b02b35dd69c30e2a8f40d234dfb)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 添加特殊歌曲文件类型 TRY_OGG_640 ([fef7e8c](https://github.com/L-1124/QQMusicApi/commit/fef7e8ceb220aa477ea7d8498f8ebfd240f72cc6)) by [@L-1124](https://github.com/L-1124)
+* **(user)** 新增收藏/取消收藏歌单 API ([7865434](https://github.com/L-1124/QQMusicApi/commit/7865434782dd205815222fe716f52bac9f84aeec)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* **(user)** 新增 FeedbackBlack 黑名单 API ([4340554](https://github.com/L-1124/QQMusicApi/commit/4340554aaaafaef175eead7ebced596538bc65e2)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 启用 FastAPI 内置 Swagger UI 和 ReDoc，更新文档地址说明 ([a3245ad](https://github.com/L-1124/QQMusicApi/commit/a3245ad3d3863c7f7eec94352d169a32ba4478c6)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 重构 Dockerfile 为多阶段构建，修复非 root 用户 uv 缓存权限问题 ([00e16a3](https://github.com/L-1124/QQMusicApi/commit/00e16a37b62e989de37232e8af7e77167a28e823)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(core)** 移除 _session_cache 冗余缓存，简化会话验证逻辑 ([0b12b9d](https://github.com/L-1124/QQMusicApi/commit/0b12b9d041a8be24ad84d60bd2ceaed76b81fe92)) by [@L-1124](https://github.com/L-1124)
+* **(models)** [**breaking**] 将所有模型中的 alias 统一替换为 validation_alias，隔离序列化字段名 ([c611b91](https://github.com/L-1124/QQMusicApi/commit/c611b91d607d36327662a80d0e126a6958b21bd5)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 移除冗余的 _require_login 调用，统一使用 require_login 参数 ([1a666f4](https://github.com/L-1124/QQMusicApi/commit/1a666f45ae968c235066c07e8b3e82096c3fc668)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 将 _require_login 收敛到 _build_request 的 require_login 参数中 ([d1a92ca](https://github.com/L-1124/QQMusicApi/commit/d1a92ca07d5a98f3f443453e5fc77b8f8c8dc44e)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(coding)** 更新需登录接口的编码规范，使用 require_login 参数替代 _require_login ([9e56215](https://github.com/L-1124/QQMusicApi/commit/9e562152ec8039b3045ae6c51006401c93b36a36)) by [@L-1124](https://github.com/L-1124)
+* **(dislike)** 更新不喜欢列表项和响应数据的文档说明 ([5dbf711](https://github.com/L-1124/QQMusicApi/commit/5dbf711e46a69f99940f048504446b9e074fd21f)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 更新二维码和手机验证码登录状态的文档注释 ([f31d4d0](https://github.com/L-1124/QQMusicApi/commit/f31d4d0132cb61a9935ebea92657fcfa6591926c)) by [@L-1124](https://github.com/L-1124)
+* **(readme)** 添加 DeepWiki 相关链接 ([fcea758](https://github.com/L-1124/QQMusicApi/commit/fcea758b80a824cb513a8bdfc8b247da786f5a1e)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @jinzhongjia [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* @github-actions[bot]
+
+## [[0.6.7](https://github.com/L-1124/QQMusicApi/compare/v0.6.6..v0.6.7)] - 2026-06-17
 
 ### 功能更新
 
+* **(login)** 新增登录异常子类和错误码映射 ([0ef9645](https://github.com/L-1124/QQMusicApi/commit/0ef9645806c9778cfa6214dd60fa56644568c276)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#269](https://github.com/L-1124/QQMusicApi/pull/269)
+* **(qimei)** 增加 24 小时过期重新获取逻辑 ([05aed29](https://github.com/L-1124/QQMusicApi/commit/05aed29096dff31b7d0cbb26ccc66ec50da38bdc)) by [@L-1124](https://github.com/L-1124)
 * **(web)** 添加 has_sheet 路由 ([9e7a143](https://github.com/L-1124/QQMusicApi/commit/9e7a1439ff597ae43a4ef99d88ec08ee32889b9a)) by [@L-1124](https://github.com/L-1124)
 
 ### 文档更新
 
+* **(coding)** 重写 API 编写指南，补充开发细节 ([9db46de](https://github.com/L-1124/QQMusicApi/commit/9db46def73ec6c2d9826c4a15bc2eb7ba9ed0f37)) by [@L-1124](https://github.com/L-1124)
+* 为固定请求平台的 API 补充 docstring 说明 ([aba712e](https://github.com/L-1124/QQMusicApi/commit/aba712e56a7485b4184941480c05f370cd53c548)) by [@L-1124](https://github.com/L-1124)
 * 完善快速开始文档并新增多篇核心教程 ([d6143cd](https://github.com/L-1124/QQMusicApi/commit/d6143cdc047ebeb4963b061680a21103ba3d58d4)) by [@L-1124](https://github.com/L-1124)
 
 ### 贡献者
 
 * @L-1124
+* @jinzhongjia [#269](https://github.com/L-1124/QQMusicApi/pull/269)
 * @github-actions[bot]
+* @renovate[bot]
 
 ## [[0.6.6](https://github.com/L-1124/QQMusicApi/compare/v0.6.5..v0.6.6)] - 2026-06-13
 

qqmusic_api_python-0.6.9/examples/upload_file.py

@@ -0,0 +1,33 @@
+"""辅助功能文件上传示例."""
+
+import asyncio
+
+from qqmusic_api import Client
+from qqmusic_api.modules.helper_utils import UploadFileSession
+
+
+async def main() -> None:
+    """文件上传示例."""
+    file_to_upload = ""
+
+    async with Client() as client:
+        session = UploadFileSession(
+            api=client.helper,
+            bus_id="songlist",  # 歌单封面
+            max_concurrency=3,
+        )
+
+        object_infos = await session.upload([file_to_upload])
+        print(f"总计成功上传 {len(object_infos)} 个文件!")
+        for info in object_infos:
+            print(f"存储桶: {info.storage.bucket.name}")
+            print(f"区域:   {info.storage.bucket.region}")
+            print(f"对象键: {info.storage.object_key}")
+            print(f"CDN 地址: {info.url.cdn_url}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\n用户取消操作")

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/pyproject.toml

@@ -49,6 +49,11 @@ documentation = "https://l-1124.github.io/QQMusicApi/"
 homepage = "https://l-1124.github.io/QQMusicApi/"
 repository = "https://github.com/l-1124/QQMusicApi"
 
+[project.optional-dependencies]
+upload = [
+    "cos-python-sdk-v5>=1.9.44",
+]
+
 [dependency-groups]
 dev = [
   "tarsio[cli]>=0.5.1",
@@ -56,6 +61,7 @@ dev = [
   { include-group = "docs" },
   { include-group = "linting" },
   { include-group = "testing" },
+  { include-group = "helper" },
 ]
 docs = [
   "docstring-inheritance>=3.0.0",
@@ -65,6 +71,9 @@ docs = [
   "mkdocstrings-python>=2.0.3",
   "zensical>=0.0.30",
 ]
+helper = [
+    "cos-python-sdk-v5>=1.9.44",
+]
 linting = [
   "prek>=0.3.5",
   "pyrefly>=0.56.0",

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/qqmusic_api/__init__.py

@@ -22,7 +22,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.6.7"
+__version__ = "0.6.9"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/qqmusic_api/core/client.py

@@ -17,7 +17,7 @@ from urllib3.util.retry import Retry
 from ..algorithms import zzc_sign
 from ..models.request import Credential, JceRequest, JceRequestItem, JceResponse, JceResponseItem, RequestItem
 from ..utils.common import bool_to_int
-from ..utils.device import DeviceManager
+from ..utils.device import Device, DeviceManager
 from ..utils.qimei import QimeiManager
 from .exceptions import (
     ApiDataError,
@@ -27,6 +27,7 @@ from .exceptions import (
     HTTPError,
     NetworkError,
     RatelimitedError,
+    SignatureRequiredError,
 )
 from .request import Request, RequestResultT, _build_result
 from .versioning import DEFAULT_VERSION_POLICY, Platform, VersionPolicy
@@ -34,6 +35,7 @@ from .versioning import DEFAULT_VERSION_POLICY, Platform, VersionPolicy
 if TYPE_CHECKING:
     from ..modules.album import AlbumApi
     from ..modules.comment import CommentApi
+    from ..modules.helper import HelperApi
     from ..modules.login import LoginApi
     from ..modules.lyric import LyricApi
     from ..modules.mv import MvApi
@@ -107,7 +109,6 @@ class Client:
 
         self._version_policy: VersionPolicy = DEFAULT_VERSION_POLICY
         self._session_lock = anyio.Lock()
-        self._session_initialized = False
         self._qimei_manager = QimeiManager(
             device_store=self._device_store,
             app_version=self._version_policy.get_qimei_app_version(),
@@ -116,12 +117,22 @@ class Client:
         )
 
     async def _ensure_session(self) -> None:
+        """获取 `Platform.ANDROID` 会话信息."""
+
+        def _is_session_valid(dev: "Device") -> bool:
+            return (
+                dev.session_save_time is not None
+                and (int(time.time()) - dev.session_save_time) < 86400
+                and bool(dev.session_uid and dev.session_sid)
+            )
+
+        device = await self._device_store.get_device()
+        if _is_session_valid(device):
+            return
+
         async with self._session_lock:
-            if self._session_initialized:
-                return
             device = await self._device_store.get_device()
-            if device.session_uid and device.session_sid:
-                self._session_initialized = True
+            if _is_session_valid(device):
                 return
 
             finalcomm = self._version_policy.build_comm(
@@ -168,8 +179,15 @@ class Client:
             device.session_uid = str(session_data["uid"])
             device.session_sid = session_data["sid"]
             device.session_vkey = session_data.get("vkey")
+            device.session_save_time = int(time.time())
             await self._device_store.save_device()
-            self._session_initialized = True
+
+    @cached_property
+    def helper(self) -> "HelperApi":
+        """辅助模块."""
+        from ..modules.helper import HelperApi
+
+        return HelperApi(self)
 
     @cached_property
     def comment(self) -> "CommentApi":
@@ -604,8 +622,9 @@ class Client:
                 "RequestResultT",
                 {"code": code, "data": data} if request.is_jce else item,
             )
-
         match code:
+            case 2000:
+                raise SignatureRequiredError(code=code, data=data)
             case 2001:
                 raise RatelimitedError(code=code, data=data)
             case 1000 | 104401 | 104400:

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/qqmusic_api/core/exceptions.py

@@ -19,6 +19,7 @@ __all__ = [
     "LoginRateLimitError",
     "NetworkError",
     "RatelimitedError",
+    "SignatureRequiredError",
 ]
 
 
@@ -202,3 +203,10 @@ class LoginRateLimitError(LoginError):
         data: Any = None,
     ):
         super().__init__(message, code=code, data=data)
+
+
+class SignatureRequiredError(CgiApiException):
+    """请求需要签名 (code=2000)."""
+
+    def __init__(self, *, code: int = 2000, data: Any = None) -> None:
+        super().__init__("请求需要签名", code=code, data=data)

qqmusic_api_python-0.6.9/qqmusic_api/models/album.py

@@ -0,0 +1,121 @@
+"""Album API 返回模型定义."""
+
+from pydantic import Field
+
+from .base import Album, Singer, Song
+from .request import Response
+
+
+class AlbumDetail(Album):
+    """专辑详情页返回的核心专辑信息.
+
+    Attributes:
+        subtitle: 专辑副标题.
+        time_public: 发行日期.
+        desc: 专辑简介.
+        language: 专辑语种.
+        album_type: 专辑类型描述.
+        genre: 专辑流派文本.
+        wikiurl: 百科链接.
+    """
+
+    subtitle: str = ""
+    time_public: str = Field(default="", validation_alias="publishDate")
+    desc: str = ""
+    language: str = ""
+    album_type: str = Field(default="", validation_alias="albumType")
+    genre: str = ""
+    wikiurl: str = ""
+
+
+class AlbumCompany(Response):
+    """专辑详情接口中的发行公司信息.
+
+    Attributes:
+        id: 公司 ID.
+        name: 公司名称.
+        is_show: 是否展示.
+        brief: 公司简介.
+    """
+
+    id: int = Field(validation_alias="ID")
+    name: str
+    is_show: int = Field(validation_alias="isShow")
+    brief: str = ""
+
+
+class GetAlbumDetailResponse(Response):
+    """专辑详情接口聚合后的响应体.
+
+    Attributes:
+        album: 专辑基础信息与补充描述.
+        company: 发行公司信息.
+        singers: 专辑署名歌手列表.
+    """
+
+    album: AlbumDetail = Field(validation_alias="basicInfo")
+    company: AlbumCompany
+    singers: list[Singer] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.singer.singerList"})
+
+
+class GetAlbumSongResponse(Response):
+    """专辑歌曲列表接口返回的分页结果.
+
+    Attributes:
+        album_mid: 专辑 MID.
+        total_num: 歌曲总数.
+        song_list: 当前响应携带的专辑歌曲列表.
+    """
+
+    album_mid: str = Field(validation_alias="albumMid")
+    total_num: int = Field(validation_alias="totalNum")
+    song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})
+
+
+class NewAlbumItem(Album):
+    """新碟上架列表中的单张专辑摘要.
+
+    Attributes:
+        singers: 专辑署名歌手列表.
+        release_time: 发行日期, 格式通常为 YYYY-MM-DD.
+        type: 专辑类型.
+        area: 地区标识.
+        genre: 流派标识.
+        language: 语种标识.
+    """
+
+    singers: list[Singer] = Field(default_factory=list)
+    release_time: str = ""
+    type: int = 0
+    area: int = 0
+    genre: int = 0
+    language: int = 0
+
+
+class GetNewAlbumResponse(Response):
+    """新碟上架接口的响应体.
+
+    Attributes:
+        total: 该地区下新碟总数.
+        albums: 当前页新碟列表.
+    """
+
+    total: int = 0
+    albums: list[NewAlbumItem] = Field(default_factory=list)
+
+
+class AlbumFavWriteResponse(Response):
+    """收藏 / 取消收藏专辑的写操作响应.
+
+    Attributes:
+        result: 操作结果码, 0 表示成功.
+        failed_album_id: 操作失败的专辑 ID 列表, 全部成功时为空.
+    """
+
+    result: int = 0
+    failed_album_id: list[int] = Field(default_factory=list, validation_alias="v_failedAlbumId")
+
+    @property
+    def success(self) -> bool:
+        """是否操作成功 (result 为 0 且无失败项)."""
+        return self.result == 0 and not self.failed_album_id

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/qqmusic_api/models/base.py

@@ -18,21 +18,17 @@ _PHOTO_NEW_SIZE_SEGMENTS: Final[dict[int, str]] = {
 }
 
 
-def _normalize_cover_size(size: CoverSize) -> str:
-    """返回 `photo_new` 模板使用的尺寸片段."""
-    try:
-        return _PHOTO_NEW_SIZE_SEGMENTS[size]
-    except KeyError as exc:
-        raise ValueError("not supported size") from exc
-
-
 def _build_photo_new_cover_url(kind: str, mid: str, size: CoverSize) -> str:
     """按 `photo_new` 规则拼接封面链接."""
     normalized_mid = mid.strip()
     if not normalized_mid:
         return ""
 
-    return f"https://y.gtimg.cn/music/photo_new/{kind}{_normalize_cover_size(size)}M000{normalized_mid}.jpg"
+    try:
+        cover_size = _PHOTO_NEW_SIZE_SEGMENTS[size]
+        return f"https://y.gtimg.cn/music/photo_new/{kind}{cover_size}M000{normalized_mid}.jpg"
+    except KeyError as exc:
+        raise ValueError("not supported size") from exc
 
 
 class Singer(Response):

{qqmusic_api_python-0.6.7 → qqmusic_api_python-0.6.9}/qqmusic_api/models/comment.py

@@ -85,29 +85,29 @@ class CommentItem(Response):
         sub_comments: 子评论列表.
     """
 
-    cmid: str = Field(alias="CmId")
-    seq_no: str = Field(alias="SeqNo")
-    nick: str = Field(alias="Nick")
-    avatar: str = Field(alias="Avatar")
-    encrypt_uin: str = Field(alias="EncryptUin")
-    content: str = Field(alias="Content")
-    pub_time: int = Field(alias="PubTime")
-    praise_num: int = Field(alias="PraiseNum")
-    reply_cnt: int = Field(alias="ReplyCnt")
-    is_praised: int = Field(alias="IsPraised")
-    is_self: int = Field(alias="IsSelf")
-    state: int = Field(alias="State")
-    hot_score: str = Field(alias="HotScore")
-    rec_score: str = Field(alias="RecScore")
-    song_id: int = Field(alias="SongId")
-    song_name: str = Field(alias="SongName")
-    singer_names: str = Field(alias="SingerNames")
-    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, alias="SongTsElems")
-    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, alias="HashTagList")
-    little_tails: list[dict[str, Any]] = Field(default_factory=list, alias="LittleTails")
-    icon_list: list[dict[str, Any]] = Field(default_factory=list, alias="IconList")
-    vip_ui: dict[str, Any] = Field(default_factory=dict, alias="VipUI")
-    sub_comments: list[dict[str, Any]] = Field(default_factory=list, alias="SubComments")
+    cmid: str = Field(validation_alias="CmId")
+    seq_no: str = Field(validation_alias="SeqNo")
+    nick: str = Field(validation_alias="Nick")
+    avatar: str = Field(validation_alias="Avatar")
+    encrypt_uin: str = Field(validation_alias="EncryptUin")
+    content: str = Field(validation_alias="Content")
+    pub_time: int = Field(validation_alias="PubTime")
+    praise_num: int = Field(validation_alias="PraiseNum")
+    reply_cnt: int = Field(validation_alias="ReplyCnt")
+    is_praised: int = Field(validation_alias="IsPraised")
+    is_self: int = Field(validation_alias="IsSelf")
+    state: int = Field(validation_alias="State")
+    hot_score: str = Field(validation_alias="HotScore")
+    rec_score: str = Field(validation_alias="RecScore")
+    song_id: int = Field(validation_alias="SongId")
+    song_name: str = Field(validation_alias="SongName")
+    singer_names: str = Field(validation_alias="SingerNames")
+    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SongTsElems")
+    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="HashTagList")
+    little_tails: list[dict[str, Any]] = Field(default_factory=list, validation_alias="LittleTails")
+    icon_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="IconList")
+    vip_ui: dict[str, Any] = Field(default_factory=dict, validation_alias="VipUI")
+    sub_comments: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SubComments")
 
 
 class CommentListResponse(Response):
@@ -136,13 +136,13 @@ class CommentListResponse(Response):
     has_more: int = Field(json_schema_extra={"jsonpath": "$.CommentList.HasMore"})
     next_offset: int = Field(json_schema_extra={"jsonpath": "$.CommentList.NextOffset"})
     total: int = Field(json_schema_extra={"jsonpath": "$.CommentList.Total"})
-    total_cm_num: int = Field(alias="TotalCmNum")
-    comment_tip: str = Field(alias="CommentTip")
-    comment_h5_page: str = Field(alias="CommentH5Page")
-    has_ts_cm: int = Field(alias="HasTsCm")
-    share_cnt: int = Field(alias="ShareCnt")
-    msg: str = Field(alias="Msg")
-    sub_code: int = Field(alias="SubCode")
+    total_cm_num: int = Field(validation_alias="TotalCmNum")
+    comment_tip: str = Field(validation_alias="CommentTip")
+    comment_h5_page: str = Field(validation_alias="CommentH5Page")
+    has_ts_cm: int = Field(validation_alias="HasTsCm")
+    share_cnt: int = Field(validation_alias="ShareCnt")
+    msg: str = Field(validation_alias="Msg")
+    sub_code: int = Field(validation_alias="SubCode")
 
 
 class MomentCommentItem(Response):
@@ -167,22 +167,22 @@ class MomentCommentItem(Response):
         little_tails: 尾巴挂件列表.
     """
 
-    cmid: str = Field(alias="CmId")
-    seq_no: str = Field(alias="SeqNo")
-    content: str = Field(alias="Content")
-    encrypt_uin: str = Field(alias="EncryptUin")
-    pub_time: int = Field(alias="PubTime")
-    praise_num: int = Field(alias="PraiseNum")
-    reply_cnt: int = Field(alias="ReplyCnt")
-    state: int = Field(alias="State")
-    is_self: int = Field(alias="IsSelf")
-    location: str = Field(alias="Location")
-    phone_type: str = Field(alias="PhoneType")
-    pic: str = Field(alias="Pic")
-    pic_size: str = Field(alias="PicSize")
-    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, alias="SongTsElems")
-    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, alias="HashTagList")
-    little_tails: list[dict[str, Any]] = Field(default_factory=list, alias="LittleTails")
+    cmid: str = Field(validation_alias="CmId")
+    seq_no: str = Field(validation_alias="SeqNo")
+    content: str = Field(validation_alias="Content")
+    encrypt_uin: str = Field(validation_alias="EncryptUin")
+    pub_time: int = Field(validation_alias="PubTime")
+    praise_num: int = Field(validation_alias="PraiseNum")
+    reply_cnt: int = Field(validation_alias="ReplyCnt")
+    state: int = Field(validation_alias="State")
+    is_self: int = Field(validation_alias="IsSelf")
+    location: str = Field(validation_alias="Location")
+    phone_type: str = Field(validation_alias="PhoneType")
+    pic: str = Field(validation_alias="Pic")
+    pic_size: str = Field(validation_alias="PicSize")
+    song_ts_elems: list[dict[str, Any]] = Field(default_factory=list, validation_alias="SongTsElems")
+    hash_tag_list: list[dict[str, Any]] = Field(default_factory=list, validation_alias="HashTagList")
+    little_tails: list[dict[str, Any]] = Field(default_factory=list, validation_alias="LittleTails")
 
 
 class MomentCommentResponse(Response):
@@ -198,11 +198,11 @@ class MomentCommentResponse(Response):
     """
 
     comments: list[MomentCommentItem] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.CmList[*]"})
-    has_more: int = Field(alias="HasMore")
-    next_pos: str = Field(default="", alias="NextPos")
-    hint: str = Field(alias="Hint")
-    prev_list_loaded: int = Field(alias="PrevListLoaded")
-    map_cm_ext: dict[str, dict[str, Any]] = Field(default_factory=dict, alias="MapCmExt")
+    has_more: int = Field(validation_alias="HasMore")
+    next_pos: str = Field(default="", validation_alias="NextPos")
+    hint: str = Field(validation_alias="Hint")
+    prev_list_loaded: int = Field(validation_alias="PrevListLoaded")
+    map_cm_ext: dict[str, dict[str, Any]] = Field(default_factory=dict, validation_alias="MapCmExt")
 
 
 class AddCommentResponse(Response):
@@ -217,9 +217,9 @@ class AddCommentResponse(Response):
         verify_url: 验证码 URL (如果需要).
     """
 
-    subcode: int = Field(alias="SubCode")
-    msg: str = Field(alias="Msg")
-    id: str = Field(alias="AddedCmId")
-    parent: str = Field(alias="ParentCmId")
+    subcode: int = Field(validation_alias="SubCode")
+    msg: str = Field(validation_alias="Msg")
+    id: str = Field(validation_alias="AddedCmId")
+    parent: str = Field(validation_alias="ParentCmId")
     floor: int = Field(json_schema_extra={"jsonpath": "$.Floor.Num"})
-    verify_url: str = Field(alias="VerifyUrl")
+    verify_url: str = Field(validation_alias="VerifyUrl")