正在加载...

QQ音乐 API 文档

提供丰富的QQ音乐相关API，包括音乐搜索、歌单获取、歌词查询、用户信息等功能。

浏览 API 查看示例

概览

QQ音乐 API 提供了一系列与QQ音乐相关的接口，支持音乐搜索、歌单管理、歌词查询、用户信息获取等功能。 所有API都需要携带有效的cookies信息才能正常调用。

音乐搜索

根据关键词搜索歌曲、歌手、专辑等信息。

歌单管理

获取推荐歌单、分类歌单、歌单详情等。

用户信息

获取用户个人信息、金币、签到状态等。

认证

所有API请求都需要携带有效的QQ音乐cookies信息，支持以下几种方式：

方式一：通过请求头携带 

GET /api/search?query=周杰伦 HTTP/1.1
Host: 127.0.0.1:3000
Uin: 123456789
Qm-keyst: your_music_key

方式二：通过Cookies携带 

GET /api/search?query=周杰伦 HTTP/1.1
Host: 127.0.0.1:3000
Cookie: uin=123456789; qm_keyst=your_music_key; qqmusic_key=your_music_key

方式三：通过请求体携带（仅POST请求） 

POST /api/sign HTTP/1.1
Host: 127.0.0.1:3000
Content-Type: application/json

{
  "musicid": "123456789",
  "musickey": "your_music_key",
  "type": "continue"
}

API 端点

API 目录

用户相关

系统管理

报时相关

音乐相关

刷歌相关

评论相关

图片处理

扫码登录获取 CK

点击展开

通过扫码登录获取 QQ 音乐的 cookies 信息

GET

请求端点

/api/login/qrcode

参数

无

检查登录状态

点击展开

检查扫码登录状态，获取登录后的 cookies 信息

调用次数: 0 GET

请求端点

/api/login/check?key=登录会话密钥

参数

参数名 类型 必填 描述
key string 是 登录会话密钥，通过 /api/login/qrcode 获取

文字转图片

点击展开

将文字转换为手写风格的图片，支持中英文字符和自定义参数

POST

请求端点

/api/text_to_image

请求体

{
  "text": "Hello World 你好世界",     // 文字内容（必需）
  "font_size": 32,                    // 字体大小（可选，默认32）
  "color": "#FF0000",                 // 颜色代码（可选，默认黑色/随机颜色）
  "width": 800,                      // 图片宽度（可选，默认800）
  "height": 400,                     // 图片高度（可选，默认400）
  "padding": 20,                      // 内边距（可选，默认20）
  "background_image": "true",          // 是否使用背景图（可选，默认true）
  "type": 1                           // 生成类型（可选，默认1）
}

参数说明：

  • text：要转换的文字内容，支持中英文字符（必需）
  • font_size：字体大小，默认32像素（可选）
  • color：文字颜色，十六进制格式，默认黑色（type=1）或随机颜色（type=2）（可选）
  • width：图片宽度，默认800像素（可选）
  • height：图片高度，默认400像素（可选）
  • padding：图片内边距，默认20像素（可选）
  • background_image：是否使用背景图，默认true（type=1）或false（type=2）（可选）
  • type：生成类型，1=默认模式（带背景和下划线），2=无背景无下划线（可选，默认1）

特殊说明：

  • 不传入color参数时：type=1默认黑色，type=2默认随机颜色
  • 不传入background_image参数时：type=1默认使用手写背景，type=2默认不使用背景
  • type=2时：默认无背景无下划线，每行使用随机颜色，相邻行颜色不同
  • 支持#RANDOM手动指定使用随机颜色
  • 支持布尔值和字符串格式的参数：如background_image: true或background_image: "true"
  • 支持数字和字符串格式的type参数：如type: 2或type: "2"

使用示例

Type 1：默认模式（带背景和下划线，黑色文字）
curl -X POST http://127.0.0.1:3000/api/text_to_image \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World\n你好世界\n这是第三行", "type": 1}'
Type 2：无背景无下划线（随机颜色）
curl -X POST http://127.0.0.1:3000/api/text_to_image \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World\n你好世界\n这是第三行", "type": 2}'
Type 2带背景图
curl -X POST http://127.0.0.1:3000/api/text_to_image \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World\n你好世界", "type": 2, "background_image": true}'
指定颜色
curl -X POST http://127.0.0.1:3000/api/text_to_image \
  -H "Content-Type: application/json" \
  -d '{"text": "自定义颜色", "color": "#FF6B6B", "type": 1}'
使用随机颜色
curl -X POST http://127.0.0.1:3000/api/text_to_image \
  -H "Content-Type: application/json" \
  -d '{"text": "随机颜色", "color": "#RANDOM", "type": 1}'

整点报时

点击展开

根据当前时间返回对应的报时语音文件

GET

请求端点

/api/time

参数

参数名 类型 必填 描述
type number 否 语音类型：0=默认报时语音，1=苏沫颜报时语音，2=马思维报时语音（默认0）

返回值

MP3格式的语音文件

示例

获取默认报时语音：

/api/time

获取苏沫颜报时语音：

/api/time?type=1

获取马思维报时语音：

/api/time?type=2

节日查询

点击展开

查询当前日期附近的节日信息

GET

请求端点

/api/holiday

参数

参数名 类型 必填 描述
num number 否 返回节日数量，默认5个

返回值

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "name": "节日名称",
      "date": "2026-02-16",
      "description": "节日描述",
      "type": ["National holiday"],
      "locations": "All"
    }
  ]
}

示例

获取默认5个节日：

/api/holiday

获取10个节日：

/api/holiday?num=10

ocr

点击展开

ocr识别

POST

请求端点

/api/ocr

请求体

{
  "base64": "Base64 编码的图片数据",
  "return_image": false
}

解析二维码

点击展开

解析二维码图片，支持 Base64 或图片 URL

POST

请求端点

/api/qrcode/parse

请求体

{
  "base64": "Base64 编码的图片数据", // 可选
  "image_url": "图片 URL 或本地路径" // 可选
}

图片转apng

点击展开

将jpg、png和gif图片转换为apng动图

POST

请求端点

/api/image/toapng

请求体

{
  "base64": ["Base64 编码的图片数据1", "Base64 编码的图片数据2"], // 多个图片的base64
  "config": {
    "delay_num": 1, // 延迟分子
    "delay_den": 2 // 延迟分母，控制动画速度
  }
}

参数说明：

  • delay_num：延迟时间的分子部分
  • delay_den：延迟时间的分母部分
  • 实际延迟时间 = delay_num / delay_den 秒
  • 示例：
  • - delay_num: 1, delay_den: 2 → 每帧延迟 0.5 秒
  • - delay_num: 1, delay_den: 10 → 每帧延迟 0.1 秒（动画速度更快）
  • - delay_num: 2, delay_den: 1 → 每帧延迟 2 秒（动画速度更慢）

响应

{
  "code": 0,
  "msg": "成功",
  "data": {
    "base64": "data:image/png;base64,转换后的apng图片数据"
  }
}

图床上传

点击展开

上传图片到图床，自动转换为webp格式（GIF保持原样），支持设置过期时间

POST

请求端点

/api/image/upload

请求体

{
  "base64": "Base64 编码的图片数据", // 图片的base64编码
  "config": {
    "expire": 600, // 过期时间，单位秒，默认10分钟
    "compress": 1, // 压缩阈值，单位MB，默认1
    "compress_target": 400 // 压缩目标大小，单位KB，默认400
  }
}

参数说明：

  • base64：Base64编码的图片数据，支持jpg、png、gif等格式
  • config.expire：图片过期时间，单位秒，默认600秒（10分钟）
  • config.compress：压缩阈值，单位MB，默认1。当图片大小超过此值时会自动压缩（GIF不压缩）
  • config.compress_target：压缩目标大小，单位KB，默认400。压缩后的图片大小会尽量接近但不超过此值

响应

{
  "code": 0,
  "msg": "成功",
  "data": {
    "url": "/api/image/xxxxxxxxxxxxxxxx.webp", // 图片访问链接
    "expire": 1730800000 // 过期时间戳
  }
}

图片访问

点击展开

访问图床上上传的图片

GET

请求端点

/api/image/{filename}

参数

参数名 类型 必填 描述
filename string 是 图片文件名，通过 /api/image/upload 获取

响应

返回图片文件，Content-Type 根据图片类型自动设置

随机妹子QQ号

点击展开

随机返回一个妹子QQ号

GET

请求端点

/api/random_qq

参数

无

响应

{
  "code": 0,
  "msg": "成功",
  "data": {
    "qq": "1611934845"
  }
}

搜索音乐

点击展开

根据关键词搜索音乐

调用次数: 0 GET

请求端点

/api/search?query=关键词&page=1&page_size=15

参数

参数名 类型 必填 描述
query string 是 搜索关键词
page number 否 页码，默认 1
page_size number 否 每页结果数量，默认 15

获取歌单详情

点击展开

根据歌单ID获取歌单详细信息

调用次数: 0 GET

请求端点

/api/playlist?id=歌单ID&num=30

参数

参数名 类型 必填 描述
id string 是 歌单ID
num number 否 获取歌曲数量，默认 30

获取用户信息

点击展开

获取当前用户的详细信息

调用次数: 0 GET

请求端点

/api/user

参数

无

签到

点击展开

每日签到领取金币

POST

请求端点

/api/sign

请求体

{
  "type": "continue" // 签到类型，默认 continue
}

添加评论

点击展开

为歌曲、专辑或歌单添加评论

调用次数: 0 POST

请求端点

/api/addcomment

请求体

{
  "content": "评论内容", // 评论内容
  "bizid": "业务ID", // 歌曲ID、专辑ID或歌单ID
  "biztype": 1, // 业务类型：1=歌曲，2=专辑，3=歌单
  "repliedcmid": null // 回复的评论ID，默认 null
}

创建音乐金币任务

点击展开

提交音乐金币任务，系统会自动执行领取金币操作

调用次数: 0 POST

请求端点

/api/coin/task

参数

通过请求头或Cookies携带 musicid 和 musickey

检查音乐金币任务状态

点击展开

检查提交的音乐金币任务执行状态

调用次数: 0 GET

请求端点

/api/coin/task/check?taskId=任务ID

参数

参数名 类型 必填 描述
taskId string 是 任务ID，通过 /api/coin/task 获取

授权扫码登录QQ音乐

点击展开

通过传入二维码图片的base64数据进行登录

调用次数: 0 POST

请求端点

/api/login_qrcode

请求体

{
  "base64": "二维码图片的base64数据" // 二维码图片的base64编码，支持带data:image前缀
}

获取音乐播放地址

点击展开

获取指定音质的音乐播放地址

调用次数: 0 GET

请求端点

/api/musicurl?songmid=歌曲MID&fileType=音质类型

参数

参数名 类型 必填 描述
songmid string 是 歌曲MID标识
fileType string 否 音质类型，默认'128'，支持的值：'128'（128kbps）、'320'（320kbps）、'flac'（无损音质）

获取歌词

点击展开

获取歌曲的歌词信息，支持原歌词和翻译歌词

调用次数: 0 GET

请求端点

/api/lyric?mid=歌曲MID或歌曲ID

参数

参数名 类型 必填 描述
mid string 是 歌曲MID或歌曲ID（自动判断）

id和mid互相转换

点击展开

自动判断输入是歌曲ID还是MID，返回对应的id和mid

调用次数: 0 GET

请求端点

/api/convert?id=歌曲ID或MID

参数

参数名 类型 必填 描述
id string 是 歌曲ID或歌曲MID

获取听歌报告

点击展开

获取用户的听歌报告截图，包括总计、今日、本周和本月报告

调用次数: 0 GET

请求端点

/api/listenreport

参数

无

加速歌曲播放

点击展开

加速指定歌曲的播放，增加听歌时长

调用次数: 0 POST

请求端点

/api/accelerate/song

请求体

{
  "songInfo": {
    "songName": "歌曲名",
    "singer": "歌手名",
    "singerId": "歌手ID",
    "songId": "歌曲ID"
  }
}

获取歌单用于刷歌

点击展开

获取用户歌单列表，用于刷歌操作

调用次数: 0 GET

请求端点

/api/accelerate/songlist?dirid=202&num=300

参数

参数名 类型 必填 描述
dirid number 否 歌单目录ID，201=我喜欢，202=今日推荐，默认202
num number 否 获取歌曲数量，默认300

刷新音乐密钥

点击展开

刷新用户的音乐密钥，使用QQMusicApi中的refresh()方法，确保API调用正常

调用次数: 0 POST

请求端点

/api/accelerate/refreshkey

参数

通过请求头或Cookies携带 musicid 和 musickey

实现说明

使用QQMusicApi中的refresh()方法，该方法会重新登录并获取新的音乐密钥，确保API调用的正常进行。

请求体

{
  "openid": "",
  "refresh_key": "",
  "refresh_token": ""
}

参数说明：

  • openid：用户的openid
  • refresh_key：刷新密钥
  • refresh_token：刷新令牌，仅在tme_login_type=1时使用

根据musicid获取昵称和encrypt_uin

点击展开

根据musicid获取用户的昵称和encrypt_uin

调用次数: 0 GET

请求端点

/api/musicid-to-encrypt?musicid=123456789

参数

参数名 类型 必填 描述
musicid string 是 用户的musicid

说明

该接口不需要传入验证信息，直接返回QQ音乐服务器的响应结果