基础信息
查看接口基本信息和返回格式
免责声明
接口描述
排行榜单、热门歌单、我的歌单、歌单详情;我的歌单需先绑定账号并用uin指定。
七日请求统计
接口地址
https://api.yunmge.com/api/qmusic-playlist
请求方式
返回方式
返回预览
{"type":"hot","page":1,"num":10}
计费标准
了解接口计费方式和套餐价格
接口类型
付费接口:本接口按次计费,每次调用将扣除相应额度。请确保账户余额充足。
计费方式
QPS限制
每分钟最多30次请求,每秒最多1次请求
每分钟最多120次请求,每秒最多5次请求
每日请求次数
普通用户不限制每日请求次数
会员用户不限制每日请求次数
扣费顺序
计费规则
安全认证
了解接口的认证方式和访问凭证管理
实名认证
本接口对所有用户开放,无需实名认证即可访问
认证方式
通过 HTTP Header 传递认证信息
通过 URL 参数传递认证信息
Token 管理
登录账户
使用您的账号密码登录平台,获取用户凭证
获取 Token
即可查看你的 Token 密钥
更换 Token
进入个人中心,点击「更换Token」,系统将生成新的 Token 密钥
保存 Token
请妥善保管您的 Token 密钥,泄露时请立即更换
Token 怪谈
安全建议
- 定期更换密钥,建议每 90 天更新一次
- 发现密钥泄露,请立即在个人中心「更换」该密钥
- 不要将密钥硬编码在代码中,使用环境变量存储
参数文档
了解接口的请求参数和响应字段说明
请求参数
| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
type |
string | 是 | toplists | toplists / toplist | toplists=榜单分类;toplist=榜单歌曲 |
topid |
int | 否 | 26 | 排行榜 ID | toplist 时使用 |
offset |
int | 否 | 0 | 偏移量 | toplist 分页偏移 |
| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
type |
string | 是 | hot | hot | 热门歌单 |
category |
int | 否 | 10000000 | 分类 ID | 热门歌单分类 |
sort |
int | 否 | 5 | 排序值 | 热门歌单排序 |
page |
int | 否 | 1 | 页码 | 页码 |
num |
int | 否 | 20 | 1~50 | 每页数量 |
| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
type |
string | 是 | my | my | 我的歌单 |
uin |
string | 否 | 登录返回的 uin | 不传返回已绑定账号列表;必须先通过 音乐登录接口绑定账号 |
| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
type |
string | 是 | detail | detail | 歌单详情 |
dissid |
string | 是 | 歌单 ID | 必填 | |
begin |
int | 否 | 0 | 偏移量 | 歌曲偏移 |
uin |
string | 否 | 登录返回的 uin | 我的歌单传;或传 from=my | |
from |
string | 否 | my | from=my 表示使用绑定账号 |
| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 说明 |
|---|---|---|---|---|---|
mid |
string | 否 | songmid | 与 url 二选一,输出同搜索接口详情 | |
url |
string | 否 | 音乐分享链接 | 与 mid 二选一 |
响应参数
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 提示信息 |
data
|
object | 榜单数据 |
|
│
groups
|
array | 榜单分组 |
|
│
│
├─
group
|
string | 分组名 |
|
│
│
lists
|
array | 榜单列表 |
|
│
│
│
├─
topId
|
int | 榜单 ID |
|
│
│
│
├─
name
|
string | 榜单名 |
|
│
│
│
├─
updateType
|
int | 更新类型 |
|
│
│
│
└─
pic
|
string | 榜单封面 |
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 提示信息 |
data
|
object | 榜单数据 |
|
│
├─
topId
|
int | 榜单 ID |
|
│
├─
offset
|
int | 偏移量 |
|
│
info
|
object | 榜单信息 |
|
│
│
├─
title
|
string | 榜单标题 |
|
│
│
├─
intro
|
string | 榜单说明 |
|
│
songs
|
array | 歌曲列表 |
|
│
│
├─
songmid
|
string | songmid |
|
│
│
├─
songid
|
int | songid |
|
│
│
├─
name
|
string | 歌名 |
|
│
│
├─
singer
|
string | 歌手 |
|
│
│
├─
album
|
string | 专辑 |
|
│
│
├─
interval
|
int | 时长(秒) |
|
│
│
├─
fee
|
string | 免费 / 会员 / 付费 |
|
│
│
└─
pay_play
|
int | 是否付费播放 |
|
│
└─
has_more
|
bool | 是否还有下一页 |
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 提示信息 |
data
|
object | 热门歌单数据 |
|
│
├─
type
|
string | hot |
|
│
├─
category
|
int | 分类 ID |
|
│
├─
sort
|
int | 排序值 |
|
│
├─
page
|
int | 页码 |
|
│
├─
num
|
int | 每页数量 |
|
│
├─
total
|
int | 总数 |
|
│
list
|
array | 歌单列表 |
|
│
│
├─
dissid
|
string | 歌单 ID |
|
│
│
├─
name
|
string | 歌单名 |
|
│
│
├─
cover
|
string | 封面 |
|
│
│
├─
listennum
|
int | 播放量 |
|
│
│
└─
creator
|
string | 创建者 |
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 未绑定提示使用音乐账号登录接口 |
data
|
object | 我的歌单数据 |
|
│
├─
type
|
string | my |
|
│
list
|
array | 歌单列表 |
|
│
│
├─
dissid
|
string | 歌单 ID |
|
│
│
├─
name
|
string | 歌单名 |
|
│
│
├─
song_cnt
|
int | 歌曲数 |
|
│
│
├─
listen_num
|
int | 播放量 |
|
│
│
└─
cover
|
string | 封面 |
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 提示信息 |
data
|
object | 歌单数据 |
|
│
info
|
object | 歌单信息 |
|
│
│
├─
name
|
string | 歌单名 |
|
│
│
├─
dissid
|
int | 歌单 ID |
|
│
│
├─
song_cnt
|
int | 歌曲数 |
|
│
│
├─
logo
|
string | 封面 |
|
│
│
├─
nickname
|
string | 创建者 |
|
│
songs
|
array | 歌曲列表 |
|
│
│
├─
songmid
|
string | songmid |
|
│
│
├─
name
|
string | 歌名 |
|
│
│
├─
singer
|
string | 歌手 |
|
│
│
├─
album
|
string | 专辑 |
|
│
│
├─
interval
|
int | 时长(秒) |
|
│
│
└─
fee
|
string | 免费 / 会员 / 付费 |
|
│
├─
begin
|
int | 偏移量 |
|
│
├─
total
|
int | 总数 |
|
│
└─
has_more
|
bool | 是否还有下一页 |
| 字段名 | 类型 | 说明 |
|---|---|---|
code
|
int | 状态码 |
msg
|
string | 解析成功 |
data
|
object | 歌曲数据 |
|
│
├─
n
|
string | songmid |
|
│
├─
songmid
|
string | songmid |
|
│
info
|
object | 歌曲信息 |
|
│
│
├─
name
|
string | 歌名 |
|
│
│
├─
singer
|
string | 歌手 |
|
│
│
├─
album
|
string | 专辑 |
|
│
│
├─
albummid
|
string | 专辑 mid |
|
│
│
├─
interval
|
int | 时长(秒) |
|
│
│
├─
cover
|
string | 封面 |
|
│
source
|
object | 源信息 |
|
│
│
├─
platform
|
string | 来源平台 |
|
│
│
├─
songmid
|
string | 来源 songmid |
|
│
│
├─
albummid
|
string | 来源专辑 mid |
|
│
│
├─
album
|
string | 来源专辑 |
|
│
│
├─
cover
|
string | 来源封面 |
|
│
qualities
|
array | 音质列表 |
|
│
│
├─
quality
|
string | 128 / 320 / flac |
|
│
│
├─
label
|
string | 音质名称 |
|
│
│
├─
url
|
string | 播放地址 |
|
│
│
├─
available
|
bool | 是否可用 |
|
│
│
└─
source
|
string | 音源标识 |
|
│
└─
lyric
|
string | 歌词 |
状态码
了解接口返回的状态码含义及处理方式
接口状态码
| 状态码 | 说明 |
|---|---|
200 |
请求成功(榜单、热门歌单、我的歌单、歌单详情) |
201 |
获取失败(后端返回错误) |
400 |
参数错误(type / dissid / mid 不合法) |
401 |
未绑定音乐账号(我的歌单需先登录并绑定) |
403 |
无权限查询该账号(只能查询当前 token 绑定的账号) |
服务器状态码
| 状态码 | 说明 |
|---|---|
500 |
服务器错误 |
501 |
请求接口不存在 |
502 |
请求接口已下架 |
503 |
请求接口维护中 |
504 |
缺少请求token参数 |
505 |
请求token不存在 |
506 |
请求token已被封禁 |
507 |
请求token额度不足 |
508 |
今日请求token已达上限 |
509 |
请求ip不在token白名单内 |
510 |
请求token无权使用当前接口 |
511 |
接口请求频率过高,请稍后再试 |
512 |
该接口未开启在线测试功能 |
513 |
今日在线测试次数已达上限 |
514 |
今日该接口请求次数已达上限 |
515 |
该接口为会员专属接口,请携带会员token |
516 |
该接口为会员专属接口,请开通会员 |
517 |
接口请求过于频繁,已被临时限制 |
518 |
该接口需要实名认证,请先完成实名认证 |
519 |
当前Token今日请求次数已达上限 |
520 |
当前Token已被禁止使用 |
521 |
请求token余额不足 |
522 |
请求token额度和余额均不足 |
530 |
接口服务异常,请稍后再试 |
531 |
接口响应超时,请稍后再试 |
532 |
接口暂时不可用,请稍后再试 |
533 |
接口配置异常 |
534 |
请求参数错误,请检查后重试 |
535 |
接口返回数据异常 |
在线测试
在线调试接口,实时查看响应结果
在线测试未开启
该接口暂未开启在线测试功能
示例代码
查看多种编程语言的接口调用示例
/**
* API请求DEMO-PHP
*
* 本demo支持GET与POST请求。
*/
//你申请的token密钥
$API_TOKEN = 'YOUR_TOKEN';
//API接口地址
$API_URL = 'https://api.yunmge.com/api/qmusic-playlist';
$get_post_data = array(
'key' => 'value',
);
/*发起请求API接口:
第1个参数:API接口地址URL,跟上面的同名变量相对应,无需更改。
第2个参数:API接口参数数组,跟上面的同名变量相对应,无需更改。
第3个参数:请求协议(GET或POST),一般默认GET,部分接口需要POST请求,根据实际情况修改为POST即可。
*/
$resdata = api::send($API_URL, $get_post_data, 'GET/POST'); //发起请求,注意这里要选择接口支持的协议,默认GET,可选POST
//打印请求结果
print($resdata);
///////////////你的业务代码可写在这里处理API返回的数据
/**
* API请求类
*/
class api
{
public static function send($API_URL, $get_post_data, $type)
{
$get_post_data = http_build_query($get_post_data);
$res = self::send_curl($API_URL, $type, $get_post_data, null);
return $res;
}
//封装好的CURL请求函数,支持POST|GET
public static function send_curl($API_URL, $type, $get_post_data)
{
$ch = curl_init();
if ($type == 'POST') {
curl_setopt($ch, CURLOPT_URL, $API_URL);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $get_post_data);
} elseif ($type == 'GET') {
curl_setopt($ch, CURLOPT_URL, $API_URL . '?' . $get_post_data);
}
curl_setopt($ch, CURLOPT_REFERER, $API_URL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$resdata = curl_exec($ch);
curl_close($ch);
return $resdata;
}
}
/**
* API请求DEMO-JavaScript
*
* 本demo支持GET与POST请求。
*/
//jQuery-Ajax
$.ajax({
url: 'https://api.yunmge.com/api/qmusic-playlist',
data: {
key: 'value',
},
type: 'GET/POST', //请求协议(GET或POST),一般默认GET,部分接口需要POST请求,根据实际情况修改为POST即可。
dataType: 'json',
success: function(data) {
console.log(data); //请求成功,输出结果到控制台
},
timeout: 3000, //超时时间
error: function(data) {
console.log('请求失败'); //失败处理
}
});
/**
* API请求DEMO-NodeJs
*
* 本demo支持GET与POST请求。
*/
const https = require('https');
const querystring = require('querystring');
// 定义请求选项
const options = {
hostname: 'api.yunmge.com',
path: '/api/qmusic-playlist',
method: 'GET/POST'
};
// 发送POST请求
const postData = querystring.stringify({
'key': 'value',
});
const postOptions = {
hostname: 'api.yunmge.com',
path: '/api/qmusic-playlist',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Content-Length': Buffer.byteLength(postData)
}
};
const postReq = https.request(postOptions, res => {
console.log(`statusCode: ${res.statusCode}`);
res.on('data', d => {
process.stdout.write(d);
});
});
postReq.on('error', error => {
console.error(error);
});
postReq.write(postData);
postReq.end();
import requests
url = "https://api.yunmge.com/api/qmusic-playlist"
data = {
"key": "value",
}
response = requests.post(url, data=data)
print(response.json())
package main
import (
"fmt"
"io/ioutil"
"net/http"
"net/url"
"strings"
)
func main() {
apiURL := "https://api.yunmge.com/api/qmusic-playlist"
// POST请求
data := url.Values{}
data.Set("key", "value")
resp, err := http.Post(apiURL, "application/x-www-form-urlencoded", strings.NewReader(data.Encode()))
if err != nil {
fmt.Println("请求失败:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
public class ApiRequest {
public static void main(String[] args) {
try {
String apiUrl = "https://api.yunmge.com/api/qmusic-playlist";
URL url = new URL(apiUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
// 构建POST参数
StringBuilder postData = new StringBuilder();
postData.append("key=").append(URLEncoder.encode("value", "UTF-8"));
byte[] postDataBytes = postData.toString().getBytes("UTF-8");
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Content-Length", String.valueOf(postDataBytes.length));
try (OutputStream os = conn.getOutputStream()) {
os.write(postDataBytes);
}
BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String line;
StringBuilder response = new StringBuilder();
while ((line = reader.readLine()) != null) {
response.append(line);
}
reader.close();
System.out.println(response.toString());
} catch (Exception e) {
e.printStackTrace();
}
}
}
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program {
static async Task Main() {
string apiUrl = "https://api.yunmge.com/api/qmusic-playlist";
using (HttpClient client = new HttpClient()) {
// POST请求
var formData = new Dictionary<string, string> {
{ "key", "value" },
};
var content = new FormUrlEncodedContent(formData);
HttpResponseMessage response = await client.PostAsync(apiUrl, content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
}
/**
* API请求DEMO-C
*
* 本demo支持GET与POST请求。
* 需要安装libcurl库
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <curl/curl.h>
// API地址
const char* url = "https://api.yunmge.com/api/qmusic-playlist";
// POST请求
void postRequest(CURL* curl) {
CURLcode res;
const char* postData = "key=value";
curl_easy_setopt(curl, CURLOPT_URL, url);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postData);
res = curl_easy_perform(curl);
if(res != CURLE_OK) {
fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
}
}
int main() {
CURL* curl = curl_easy_init();
if(curl) {
postRequest(curl); curl_easy_cleanup(curl);
}
return 0;
}
/**
* API请求DEMO-C++
*
* 本demo支持GET与POST请求。
* 需要安装libcurl库
*/
#include <iostream>
#include <string>
#include <curl/curl.h>
int main() {
CURL* curl = curl_easy_init();
if(curl) {
std::string apiUrl = "https://api.yunmge.com/api/qmusic-playlist";
// POST请求
std::string postData = "key=value";
curl_easy_setopt(curl, CURLOPT_URL, apiUrl.c_str());
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postData.c_str());
CURLcode res = curl_easy_perform(curl);
if(res != CURLE_OK) {
std::cerr << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;
}
curl_easy_cleanup(curl);
}
return 0;
}
.版本 2
.支持库 spec
.子程序 _启动子程序
.局部变量 url, 文本型
.局部变量 data, 文本型
.局部变量 result, 文本型
url = "https://api.yunmge.com/api/qmusic-playlist"
data = "key=value"
result = 网页_访问 (url, 1, data, , , , , , , , , )
调试输出 (result)
常见问题
查找常见问题的解决方案
计费与注意事项
- 付费:仅歌曲详情解析(mid/url)。
- 免费:榜单分类、榜单歌曲、热门歌单、我的歌单、歌单详情。
- 我的歌单需先绑定账号并传 uin;不传 uin 返回账号列表,免费。
- 公开歌单和榜单无需绑定账号;歌单详情本身免费,解析其中歌曲详情才收费。
常见问题
Q:哪些操作免费?
A:榜单分类、榜单歌曲、热门歌单、我的歌单、歌单详情都免费;只有解析歌曲详情收费。
Q:我的歌单提示未绑定怎么办?
A:先通过音乐账号登录接口绑定账号,再传 uin 查询;不传 uin 会返回已绑定账号列表,免费。
Q:uin 怎么传?
A:QQ号和微信ID统一传账号 uin,不是微信 openid。
Q:歌单详情收费吗?
A:歌单详情本身免费,返回歌曲列表;解析其中某首歌曲详情才按次收费。
Q:为什么歌单为空或提示无权限?
A:私密歌单需要用歌单所属账号的 CK 读取;账号 CK 失效、歌单被删除或设为私密都会导致读取失败。
Q:歌单如何翻页?
A:歌单详情用 begin 分页,范围 0~5000,每页 50 首;榜单用 offset 分页。