{"openapi":"3.1.0","info":{"title":"QQ音乐 Plus API","description":"基于 qqmusic-api-python 的增强 REST API 服务\n\n---\n\n## 使用说明\n\n### 认证方式\n所有接口通过 `Authorization` 请求头传递 Token。点击页面右上角「Authorize」按钮，输入 Token 值即可（无需 Bearer 前缀）。\n如果服务器未配置 `QQMUSIC_PLUS_API_TOKEN` 环境变量，则不需要认证。\n\n### 首次使用\n1. 调用 `/api/v2/auth/qr/start` 生成二维码\n2. 用手机QQ音乐扫码登录\n3. 轮询 `/api/v2/auth/qr/status` 直到登录成功\n4. 凭据自动保存到 `.env`，支持自动续登\n\n### 播放链接获取流程\n1. 调用 `/api/v2/song/cdn-dispatch` 获取 CDN 域名 (`sip`)\n2. 调用 `/api/v2/song/urls` 获取歌曲各音质的路径 (`purl`)\n3. 拼接完整链接: `sip + purl`\n\n### 通用响应格式\n成功：`{\"ok\": true, \"count\": 10, \"results\": [...]}`\n失败：`{\"ok\": false, \"detail\": \"错误原因\"}`\n","version":"0.2.0"},"paths":{"/api/v2/auth/status":{"get":{"summary":"登录状态检查","description":"检查当前凭据是否有效，支持自动续登","operationId":"auth_status_api_v2_auth_status_get","parameters":[{"name":"auto_refresh","in":"query","required":false,"schema":{"type":"boolean","description":"是否自动续登","default":true,"title":"Auto Refresh"},"description":"是否自动续登"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/auth/refresh":{"post":{"summary":"刷新凭据","description":"手动刷新登录凭据并写回 .env","operationId":"auth_refresh_api_v2_auth_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/auth/qr/start":{"post":{"summary":"生成登录二维码","description":"支持 QQ / 微信 / 手机端三种方式","operationId":"auth_qr_start_api_v2_auth_qr_start_post","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"登录方式: qq / wx / mobile","default":"qq","title":"Type"},"description":"登录方式: qq / wx / mobile"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/auth/qr/status":{"get":{"summary":"轮询二维码状态","description":"查询扫码进度，登录成功后自动保存凭据","operationId":"auth_qr_status_api_v2_auth_qr_status_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"二维码会话标识","title":"Id"},"description":"二维码会话标识"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/auth/qr/cancel":{"post":{"summary":"取消二维码会话","description":"主动取消并清理二维码会话","operationId":"auth_qr_cancel_api_v2_auth_qr_cancel_post","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","description":"二维码会话标识","title":"Id"},"description":"二维码会话标识"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/songlists":{"get":{"summary":"我的歌单","description":"获取用户自建歌单列表","operationId":"my_songlists_api_v2_me_songlists_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/fav-songs":{"get":{"summary":"我喜欢的歌曲","description":"获取用户收藏的歌曲列表","operationId":"my_fav_songs_api_v2_me_fav_songs_get","parameters":[{"name":"num","in":"query","required":false,"schema":{"type":"integer","description":"获取数量","default":20,"title":"Num"},"description":"获取数量"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/fav-songlists":{"get":{"summary":"收藏歌单","description":"获取用户收藏的他人歌单","operationId":"my_fav_songlists_api_v2_me_fav_songlists_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/fav-albums":{"get":{"summary":"收藏专辑","description":"获取用户收藏的专辑列表","operationId":"my_fav_albums_api_v2_me_fav_albums_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/fav-mvs":{"get":{"summary":"收藏MV","description":"获取用户收藏的MV列表","operationId":"my_fav_mvs_api_v2_me_fav_mvs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/vip":{"get":{"summary":"VIP信息","description":"获取用户VIP状态和有效期","operationId":"my_vip_info_api_v2_me_vip_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/music-gene":{"get":{"summary":"音乐基因","description":"获取用户听歌偏好和月度统计","operationId":"my_music_gene_api_v2_me_music_gene_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/recommend/songlists":{"get":{"summary":"推荐歌单","description":"获取每日推荐歌单","operationId":"recommend_songlists_api_v2_recommend_songlists_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/recommend/newsongs":{"get":{"summary":"推荐新歌","description":"获取每日推荐新歌","operationId":"recommend_newsongs_api_v2_recommend_newsongs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/recommend/guess":{"get":{"summary":"猜你喜欢","description":"根据听歌习惯推荐歌曲","operationId":"guess_recommend_api_v2_recommend_guess_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListResponse"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/top/categories":{"get":{"summary":"排行榜分类","description":"获取所有排行榜分类及各分类下的榜单摘要","operationId":"api_top_categories_api_v2_top_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/top/detail":{"get":{"summary":"排行榜详情","description":"获取指定排行榜的歌曲列表（分页）","operationId":"api_top_detail_api_v2_top_detail_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"排行榜ID","title":"Id"},"description":"排行榜ID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"每页数量","default":10,"title":"Num"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/songlists/create":{"post":{"summary":"创建歌单","description":"创建新的自建歌单","operationId":"api_create_songlist_api_v2_me_songlists_create_post","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌单名称","title":"Name"},"description":"歌单名称"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/songlists/delete":{"post":{"summary":"删除歌单","description":"删除指定的自建歌单","operationId":"api_delete_songlist_api_v2_me_songlists_delete_post","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"歌单 dirid","title":"Id"},"description":"歌单 dirid"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/songlists/add-songs":{"post":{"summary":"添加歌曲到歌单","description":"将歌曲添加到指定歌单","operationId":"api_add_songs_api_v2_me_songlists_add_songs_post","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"歌单 dirid","title":"Id"},"description":"歌单 dirid"},{"name":"song_id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Song Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/songlists/remove-songs":{"post":{"summary":"从歌单移除歌曲","description":"将歌曲从指定歌单中移除","operationId":"api_remove_songs_api_v2_me_songlists_remove_songs_post","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"歌单 dirid","title":"Id"},"description":"歌单 dirid"},{"name":"song_id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Song Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/like-song":{"post":{"summary":"喜欢歌曲","description":"将歌曲添加到「我喜欢」","operationId":"api_like_song_api_v2_me_like_song_post","parameters":[{"name":"song_id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Song Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/me/unlike-song":{"post":{"summary":"取消喜欢","description":"将歌曲从「我喜欢」中移除","operationId":"api_unlike_song_api_v2_me_unlike_song_post","parameters":[{"name":"song_id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Song Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/cdn-dispatch":{"get":{"summary":"CDN调度","description":"获取音频CDN域名列表，用于拼接播放链接","operationId":"api_cdn_dispatch_api_v2_song_cdn_dispatch_get","parameters":[{"name":"use_new_domain","in":"query","required":false,"schema":{"type":"boolean","description":"使用新域名","default":true,"title":"Use New Domain"},"description":"使用新域名"},{"name":"use_ipv6","in":"query","required":false,"schema":{"type":"boolean","description":"支持IPv6","default":true,"title":"Use Ipv6"},"description":"支持IPv6"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search":{"get":{"summary":"搜索歌曲","description":"按关键词搜索歌曲","operationId":"api_search_api_v2_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"每页数量","default":10,"title":"Limit"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/urls":{"get":{"summary":"获取播放链接","description":"获取歌曲播放链接，支持16种音质类型","operationId":"api_song_urls_api_v2_song_urls_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌曲MID","title":"Mid"},"description":"歌曲MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/lyric":{"get":{"summary":"获取歌词","description":"获取歌词原文、翻译、罗马音，支持QRC解密","operationId":"api_song_lyric_api_v2_song_lyric_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌曲MID","title":"Mid"},"description":"歌曲MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LyricResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/comments":{"get":{"summary":"歌曲评论","description":"获取歌曲评论（热门/最新/推荐）","operationId":"api_comments_api_v2_song_comments_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌曲ID","title":"Id"},"description":"歌曲ID"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"评论模式: hot / new / recommend","default":"hot","title":"Mode"},"description":"评论模式: hot / new / recommend"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"每页数量","default":15,"title":"Page Size"},"description":"每页数量"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/cover":{"get":{"summary":"专辑封面","description":"获取歌曲对应的专辑封面（多尺寸）","operationId":"api_song_cover_api_v2_song_cover_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌曲MID","title":"Mid"},"description":"歌曲MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/similar":{"get":{"summary":"相似歌曲","description":"获取与指定歌曲相似的歌曲列表","operationId":"api_similar_api_v2_song_similar_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/versions":{"get":{"summary":"其他版本","description":"获取歌曲的其他版本","operationId":"api_versions_api_v2_song_versions_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","description":"歌曲MID","title":"Mid"},"description":"歌曲MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/official-mv":{"get":{"summary":"官方MV","description":"获取歌曲的官方MV及播放链接","operationId":"api_official_mv_api_v2_song_official_mv_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","description":"歌曲MID","title":"Mid"},"description":"歌曲MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/related-mv":{"get":{"summary":"相关MV","description":"获取与歌曲相关的MV列表","operationId":"api_related_mv_api_v2_song_related_mv_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"歌曲ID","title":"Id"},"description":"歌曲ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/song/mv/urls":{"get":{"summary":"MV播放链接","description":"通过VID获取MV播放链接（多清晰度）","operationId":"api_mv_urls_api_v2_song_mv_urls_get","parameters":[{"name":"vid","in":"query","required":true,"schema":{"type":"string","description":"MV的VID","title":"Vid"},"description":"MV的VID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/songlist/detail":{"get":{"summary":"歌单详情","description":"获取歌单详情及歌曲列表","operationId":"api_songlist_detail_api_v2_songlist_detail_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌单ID","title":"Id"},"description":"歌单ID"},{"name":"dirid","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"歌单dirid","default":0,"title":"Dirid"},"description":"歌单dirid"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/info":{"get":{"summary":"歌手信息","description":"获取歌手基本信息（名称、头像等）","operationId":"api_singer_info_api_v2_singer_info_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/desc":{"get":{"summary":"歌手简介","description":"获取歌手详细描述（地区、风格、生日等）","operationId":"api_singer_desc_api_v2_singer_desc_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/songs":{"get":{"summary":"歌手歌曲","description":"获取歌手的歌曲列表（分页）","operationId":"api_singer_songs_api_v2_singer_songs_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"每页数量","default":10,"title":"Num"},"description":"每页数量"},{"name":"begin","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"起始位置","default":0,"title":"Begin"},"description":"起始位置"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/albums":{"get":{"summary":"歌手专辑","description":"获取歌手的专辑列表（分页）","operationId":"api_singer_albums_api_v2_singer_albums_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"每页数量","default":10,"title":"Num"},"description":"每页数量"},{"name":"begin","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"起始位置","default":0,"title":"Begin"},"description":"起始位置"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/mvs":{"get":{"summary":"歌手MV","description":"获取歌手的MV列表（分页）","operationId":"api_singer_mvs_api_v2_singer_mvs_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"每页数量","default":10,"title":"Num"},"description":"每页数量"},{"name":"begin","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"起始位置","default":0,"title":"Begin"},"description":"起始位置"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/singer/similar":{"get":{"summary":"相似歌手","description":"获取与指定歌手相似的歌手列表","operationId":"api_similar_singers_api_v2_singer_similar_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"歌手MID","title":"Mid"},"description":"歌手MID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"获取数量","default":10,"title":"Num"},"description":"获取数量"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/album/detail":{"get":{"summary":"专辑详情","description":"获取专辑详情（名称、歌手、发行日期等）","operationId":"api_album_detail_api_v2_album_detail_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"专辑MID","title":"Mid"},"description":"专辑MID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/album/songs":{"get":{"summary":"专辑歌曲","description":"获取专辑的歌曲列表（分页）","operationId":"api_album_songs_api_v2_album_songs_get","parameters":[{"name":"mid","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"专辑MID","title":"Mid"},"description":"专辑MID"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"每页数量","default":10,"title":"Num"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/singers":{"get":{"summary":"搜索歌手","description":"按关键词搜索歌手","operationId":"api_search_singers_api_v2_search_singers_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"每页数量","default":10,"title":"Limit"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/albums":{"get":{"summary":"搜索专辑","description":"按关键词搜索专辑","operationId":"api_search_albums_api_v2_search_albums_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"每页数量","default":10,"title":"Limit"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/mvs":{"get":{"summary":"搜索MV","description":"按关键词搜索MV","operationId":"api_search_mvs_api_v2_search_mvs_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"每页数量","default":10,"title":"Limit"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/songlists":{"get":{"summary":"搜索歌单","description":"按关键词搜索歌单","operationId":"api_search_songlists_api_v2_search_songlists_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"每页数量","default":10,"title":"Limit"},"description":"每页数量"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"页码","default":1,"title":"Page"},"description":"页码"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/hotkey":{"get":{"summary":"热搜词","description":"获取当前热搜关键词列表","operationId":"api_search_hotkey_api_v2_search_hotkey_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerAuth":[]}]}},"/api/v2/search/complete":{"get":{"summary":"搜索补全","description":"获取搜索关键词的自动补全建议","operationId":"api_search_complete_api_v2_search_complete_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"搜索关键词","title":"Q"},"description":"搜索关键词"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}}},"components":{"schemas":{"AuthStatusResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"authenticated":{"type":"boolean","title":"是否已认证","description":"是否已认证"},"expired":{"type":"boolean","title":"凭据是否已过期","description":"凭据是否已过期"},"musicid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"QQ音乐用户ID","description":"QQ音乐用户ID"},"detail":{"type":"string","title":"状态说明","description":"状态说明","default":""},"can_refresh":{"type":"boolean","title":"是否具备自动续登能力","description":"是否具备自动续登能力","default":false},"has_refresh_key":{"type":"boolean","title":"是否有续登密钥","description":"是否有续登密钥","default":false},"has_refresh_token":{"type":"boolean","title":"是否有续登令牌","description":"是否有续登令牌","default":false}},"type":"object","required":["ok","authenticated","expired"],"title":"AuthStatusResponse","description":"认证状态响应"},"CommentsResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"id":{"type":"string","title":"歌曲ID","description":"歌曲ID"},"mode":{"type":"string","title":"评论模式","description":"评论模式: hot(热门) / new(最新) / recommend(推荐)","default":"hot"},"page":{"type":"integer","title":"当前页码","description":"当前页码","default":1},"page_size":{"type":"integer","title":"每页数量","description":"每页数量","default":15},"total_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"当前模式评论总数","description":"当前模式评论总数"},"total_all":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"全部评论总数","description":"全部评论总数"},"has_more":{"type":"boolean","title":"是否有更多评论","description":"是否有更多评论","default":false},"comments":{"items":{},"type":"array","title":"评论列表","description":"评论列表"}},"type":"object","required":["ok","id","comments"],"title":"CommentsResponse","description":"评论响应"},"CoverResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"mid":{"type":"string","title":"歌曲MID","description":"歌曲MID"},"title":{"type":"string","title":"歌曲标题","description":"歌曲标题"},"album":{"type":"string","title":"专辑名称","description":"专辑名称"},"album_mid":{"type":"string","title":"专辑MID","description":"专辑MID"},"cover_urls":{"additionalProperties":{"type":"string"},"type":"object","title":"封面链接","description":"封面链接，key为尺寸(150/300/500/800)"}},"type":"object","required":["ok","mid","title","album","album_mid","cover_urls"],"title":"CoverResponse","description":"封面响应"},"GenericListResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"count":{"type":"integer","title":"结果数量","description":"结果数量"},"results":{"items":{},"type":"array","title":"结果列表","description":"结果列表"},"raw_hint":{"type":"string","title":"附加提示","description":"附加提示","default":""}},"type":"object","required":["ok","count","results"],"title":"GenericListResponse","description":"通用列表响应"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LyricResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"mid":{"type":"string","title":"歌曲MID","description":"歌曲MID"},"lyric":{"type":"string","title":"原文歌词","description":"原文歌词（LRC格式）"},"trans":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"翻译歌词","description":"翻译歌词"},"roma":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"罗马音歌词","description":"罗马音歌词"}},"type":"object","required":["ok","mid","lyric"],"title":"LyricResponse","description":"歌词响应"},"SearchResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"keyword":{"type":"string","title":"搜索关键词","description":"搜索关键词"},"page":{"type":"integer","title":"当前页码","description":"当前页码"},"page_size":{"type":"integer","title":"每页数量","description":"每页数量"},"count":{"type":"integer","title":"结果数量","description":"结果数量"},"results":{"items":{},"type":"array","title":"搜索结果列表","description":"搜索结果列表"}},"type":"object","required":["ok","keyword","page","page_size","count","results"],"title":"SearchResponse","description":"搜索响应"},"UrlsResponse":{"properties":{"ok":{"type":"boolean","title":"请求是否成功","description":"请求是否成功"},"mid":{"type":"string","title":"歌曲MID","description":"歌曲MID"},"title":{"type":"string","title":"歌曲标题","description":"歌曲标题"},"singers":{"items":{"type":"string"},"type":"array","title":"歌手列表","description":"歌手列表"},"album":{"type":"string","title":"专辑名称","description":"专辑名称"},"qualities":{"additionalProperties":{"type":"string"},"type":"object","title":"音质与播放链接映射","description":"音质与播放链接映射，需拼接CDN域名"}},"type":"object","required":["ok","mid","title","singers","album","qualities"],"title":"UrlsResponse","description":"播放链接响应"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"直接输入 Token 值即可（无需 Bearer 前缀）"}}}}