QQ Music API

基于 Python httpx 的 QQ 音乐 API 客户端，支持歌曲搜索、歌曲详情查询、获取播放 URL（vkey）及音频下载。

功能

• 歌曲搜索 - 按关键词搜索歌曲
• 歌曲详情 - 通过 song_mid 查询歌曲详情，获取 strMediaMid
• 获取播放 URL - 批量请求多音质，按优先级返回可用播放链接
• 音频下载 - 流式下载，支持断点安全下载和进度显示

安装

pip install httpx

快速开始

import asyncio
from qq_music import QQMusicClient

async def main():
    async with QQMusicClient() as client:  # 匿名模式
        # 搜索歌曲
        results = await client.search("周杰伦 晴天", limit=5)
        for song in results:
            print(f"[{song.song_id}] {song.display()}")

        # 查询详情补全 media_mid
        if results:
            detail = await client.get_song_detail(results[0].song_id)
            if detail:
                print(f"media_mid: {detail.media_id}")

                # 获取播放 URL
                url = await client.get_play_url(
                    song_mid=detail.song_id,
                    media_mid=detail.media_id,
                )
                if url:
                    print(f"播放地址: {url}")

asyncio.run(main())

使用 VIP 账号（获取 FLAC 高音质）

async with QQMusicClient(
    uin="你的QQ号",
    qqmusic_key="你的鉴权令牌",
) as client:
    url = await client.get_play_url(song_mid="...", media_mid="...")

获取 Cookie 方式：

1. 登录 y.qq.com
2. F12 开发者工具 → Application → Cookies
3. 复制 uin（QQ号）和 qqmusic_key（鉴权令牌）

音质优先级

前缀	格式	说明
F000	.flac	无损 FLAC（需 VIP）
M800	.mp3	320kbps MP3
M500	.mp3	128kbps MP3
C400	.m4a	128kbps M4A

测试

python test_qq_music.py

API 文档

详细 API 文档请参考 QQ_MUSIC_API.md。

注意事项

• media_mid 与 song_mid 通常不同，构造播放 URL 时必须用 media_mid
• 播放 URL 有效期约 1-2 小时，获取后应尽快使用
• 匿名模式仅能获取普通音质（MP3/M4A）
• 频繁请求可能触发风控（module_code=2001），建议加随机间隔

License

MIT