跳转至

base

models.base

定义多个接口共享的基础业务实体模型.

Singer pydantic-model

Bases: Response

表示接口响应中常见的歌手摘要信息.

ATTRIBUTE DESCRIPTION
id

歌手数字 ID.

TYPE: int

mid

歌手 Media MID, 用于请求歌手详情的核心参数.

TYPE: str

name

歌手名称.

TYPE: str

title

歌手展示标题, 通常与名称一致.

TYPE: str

type

歌手类型, 如 0 表示艺人, 1 表示组合.

TYPE: int

uin

与歌手关联的用户 ID.

TYPE: int

pmid

图片 Media ID, 用于拼接歌手头像 URL.

TYPE: str

Config:

  • populate_by_name: True
  • extra: ignore
  • frozen: True

Fields:

cover_url 

cover_url(size: CoverSize = 300) -> str

获取歌手封面链接.

Source code in qqmusic_api/models/base.py 
62
63
64
def cover_url(self, size: CoverSize = 300) -> str:
    """获取歌手封面链接."""
    return _build_photo_new_cover_url("T001", self.mid or self.pmid, size)

Album pydantic-model

Bases: Response

表示接口响应中的专辑摘要信息.

ATTRIBUTE DESCRIPTION
id

专辑数字 ID.

TYPE: int

mid

专辑 Media MID, 用于请求专辑详情的核心参数.

TYPE: str

name

专辑名称.

TYPE: str

title

专辑展示标题.

TYPE: str

subtitle

专辑副标题.

TYPE: str

time_public

发行日期, 格式通常为 YYYY-MM-DD.

TYPE: str

pmid

图片 Media ID, 用于拼接封面 URL.

TYPE: str

Fields:

cover_url 

cover_url(size: CoverSize = 300) -> str

获取专辑封面链接.

Source code in qqmusic_api/models/base.py 
88
89
90
def cover_url(self, size: CoverSize = 300) -> str:
    """获取专辑封面链接."""
    return _build_photo_new_cover_url("T002", self.mid or self.pmid, size)

File pydantic-model

Bases: Response

歌曲文件信息.

包含歌曲在不同音质等级下的文件大小(字节)信息.

ATTRIBUTE DESCRIPTION
media_mid

基础媒体标识符, 用于拼接文件名.

TYPE: str

size_24aac

极低品质 AAC 大小.

TYPE: int

size_48aac

低品质 AAC 大小.

TYPE: int

size_96aac

流畅音质 AAC 大小.

TYPE: int

size_192ogg

HQ 高品质 OGG 大小 (192k).

TYPE: int

size_192aac

HQ 高品质 AAC 大小 (192k).

TYPE: int

size_128mp3

标准音质 MP3 大小 (128k).

TYPE: int

size_320mp3

HQ 高品质 MP3 大小 (320k).

TYPE: int

size_flac

SQ 无损音质 FLAC 大小.

TYPE: int

size_dts

DTS:X 音效文件大小.

TYPE: int

size_try

试听片段文件大小.

TYPE: int

try_begin

试听片段开始时间 (毫秒).

TYPE: int

try_end

试听片段结束时间 (毫秒).

TYPE: int

size_96ogg

流畅音质 OGG 大小 (96k).

TYPE: int

size_dolby

杜比全景声文件大小.

TYPE: int

size_new

现代高级音质数组, 包含臻品系列大小.
- [0]: 臻品母带 (24Bit/192kHz).
- [1]: 臻品音质 2.0 (银河音效).
- [2]: 臻品全景声 5.1 (空间音频).
- [3]: HQ 高品质 (OGG 320k).
- [4]: 黑胶唱片 (模拟质感).
- [5]: SQ 无损音质 (OGG 640k).
- [6]: 臻品全景声 7.1.4.
- [7]: TQ 标准音质 (NAC 极致压缩).
- [9]: DTS:X (5.1 环绕声).

TYPE: list[int]

Fields:

  • media_mid (str)
  • size_24aac (int)
  • size_48aac (int)
  • size_96aac (int)
  • size_192ogg (int)
  • size_192aac (int)
  • size_128mp3 (int)
  • size_320mp3 (int)
  • size_flac (int)
  • size_dts (int)
  • size_try (int)
  • try_begin (int)
  • try_end (int)
  • size_96ogg (int)
  • size_dolby (int)
  • size_new (list[int])

Pay pydantic-model

Bases: Response

表示歌曲在播放、下载与付费上的权限信息.

ATTRIBUTE DESCRIPTION
pay_month

绿钻或付费包权限标识, 1 表示需要.

TYPE: int

price_track

单曲售价, 单位为分.

TYPE: int

price_album

专辑售价, 单位为分.

TYPE: int

pay_play

播放付费标识.

TYPE: int

pay_down

下载付费标识.

TYPE: int

pay_status

支付状态.

TYPE: int

time_free

免费试听或限免时长信息.

TYPE: int

Fields:

  • pay_month (int)
  • price_track (int)
  • price_album (int)
  • pay_play (int)
  • pay_down (int)
  • pay_status (int)
  • time_free (int)

MV pydantic-model

Bases: Response

表示歌曲关联的 MV 摘要信息.

ATTRIBUTE DESCRIPTION
id

MV 数字 ID.

TYPE: int

vid

MV VID, 常用于请求 MV 详情或播放地址.

TYPE: str

type

MV 类型.

TYPE: int

name

MV 名称.

TYPE: str

title

MV 展示标题.

TYPE: str

Fields:

SongList pydantic-model

Bases: Response

表示歌单或曲库目录的摘要信息.

ATTRIBUTE DESCRIPTION
id

歌单数字 ID.

TYPE: int

dirid

目录 ID.

TYPE: int

title

歌单标题.

TYPE: str

picurl

歌单封面地址.

TYPE: str

desc

歌单简介.

TYPE: str

songnum

歌曲数量.

TYPE: int

listennum

播放量.

TYPE: int | str

Fields:

Song pydantic-model

Bases: Response

歌曲基础模型.

包含歌曲的基础识别信息、关联对象、技术参数及播放权限控制.

ATTRIBUTE DESCRIPTION
id

歌曲数字 ID.

TYPE: int

type

歌曲类型 (1: 普通歌曲; 2: 长音频; 6: 视频/直播等).

TYPE: int

mid

歌曲 Media MID, 请求播放链接、歌词、详情的核心参数.

TYPE: str

name

歌曲名称.

TYPE: str

title

歌曲标题.

TYPE: str

subtitle

副标题, 如"电影《xxx》插曲".

TYPE: str

singer

歌手列表.

TYPE: list[Singer]

album

专辑信息.

TYPE: Album

mv

MV 信息.

TYPE: MV

file

歌曲文件信息.

TYPE: File

pay

支付属性.

TYPE: Pay

interval

时长 (秒).

TYPE: int

isonly

是否独家 (1: 是).

TYPE: int

language

语言 ID.

TYPE: int

genre

音乐流派 ID (见文档 5.3.1 映射表).

TYPE: int

index_cd

CD 索引.

TYPE: int

index_album

专辑索引.

TYPE: int

time_public

发行日期, 格式通常为 YYYY-MM-DD.

TYPE: str

status

歌曲上下架状态 (0: 正常; 1: 下架; 2: 待审核; 3: 仅限部分区域播放).

TYPE: int

label

唱片公司或特性标签 (如"经典").

TYPE: str

bpm

每分钟节拍数 (BPM), 对应 JSON 中的 bpm 字段.

TYPE: int

ov

原版标识 (1: 正宗原版; 0: 翻唱/Live).

TYPE: int

sa

64 位权益位掩码, 标识高级权益 (HQ/SQ/Hi-Res/Atmos/Master) 及试听状态.

TYPE: int

es

扩展状态/来源, 用于存放版权或协议层面的附加参数.

TYPE: str

vs

关联版本与高级媒体 MID 列表.
- [0]: 标准试听片段 MID (RS02).
- [3]: 臻品母带完整版 MID (AI00).
- [4]: 臻品音质 2.0 完整版 MID (Q000).
- [7]: 杜比全景声试听 MID (DA04).
- [8]: 臻品音质(银河)试听 MID (QA00).
- [9]: 纯人声/伴奏轨道 (O801).
- [11]: 黑胶唱片试听 MID (VA00).
- [13-17]: AI 臻品音效 (钢琴、古筝、葫芦丝、曲笛、八音盒).
- [18]: 多轨版媒体 MID (O601).
- [19-22]: AI 臻品音效 (唢呐、手碟、电吉他、架子鼓).
- [23]: 人声伴奏试听 MID (O802).
- [24]: 臻品全景声 7.1.4 完整版 MID (Q003).
- [26]: AI 臻品音效 - 卡祖笛版.
- [27]: AI 臻品音效 - 疗愈版.
- [28]: TQ 标准音质 (NAC) 完整版 MID (TL01).
- [30]: DTS:X 音效完整版 MID (DT03).
- [31]: 护耳模式完整版 MID (HE00).

TYPE: list[str]

vi

变体信息数组.
- [4]: 试听开始时间 (毫秒).
- [5]: 试听结束时间 (毫秒).
- [6]: 音质/格式标记 (1: 支持 NAC).

TYPE: list[int]

vf

音量平衡数组 (ReplayGain).
- [0]: 建议增益 (dB).
- [1]: 信号峰值幅度.
- [2]: 响度范围.

TYPE: list[float]

Fields:

cover_url 

cover_url(size: CoverSize = 300) -> str

获取歌曲封面链接.

依次使用专辑封面->首个可用歌手封面.

PARAMETER DESCRIPTION
size

封面大小.

TYPE: CoverSize DEFAULT: 300

Source code in qqmusic_api/models/base.py 
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
def cover_url(self, size: CoverSize = 300) -> str:
    """获取歌曲封面链接.

    依次使用专辑封面->首个可用歌手封面.

    Args:
        size: 封面大小.
    """
    if self.album.mid or self.album.pmid:
        return self.album.cover_url(size)

    for singer in self.singer:
        if singer.mid or singer.pmid:
            return singer.cover_url(size)

    return ""