/ 接口详情
黄盒音乐
使用某黄盒官方提供的官方API进行获取的数据
接口信息
GET / POST
api.317ak.com/api/yinyue/kuwo/api.php
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| key | string | 是 | 接口调用密钥 | |
| msg | string | 是 | 搜索的歌名(必填,不传或为空时返回错误) | 江南 |
| n | string | 否 | 选第几首(1-based)。不传或为空 => 列表模式;1=第1首,2=第2首,以此类推 | 1 |
| br | string | 否 | 音质数字，对应规格如下 | 1 |
| page | string | 否 | 搜索页码,默认1 | 1 |
| limit | string | 否 | 每页数量,默认10 | 10 |
| type | string | 是 | 输出格式。json=完整信息(默认) / text=纯链接文本 / mp3=302跳转到音频 | json |
[
{
"name": "key",
"type": "string",
"required": true,
"description": "接口调用密钥",
"example": ""
},
{
"name": "msg",
"type": "string",
"required": true,
"description": "搜索的歌名(必填,不传或为空时返回错误)",
"example": "江南"
},
{
"name": "n",
"type": "string",
"required": false,
"description": "选第几首(1-based)。不传或为空 => 列表模式;1=第1首,2=第2首,以此类推",
"example": "1"
},
{
"name": "br",
"type": "string",
"required": false,
"description": "音质数字，对应规格如下",
"example": "1"
},
{
"name": "page",
"type": "string",
"required": false,
"description": "搜索页码,默认1",
"example": "1"
},
{
"name": "limit",
"type": "string",
"required": false,
"description": "每页数量,默认10",
"example": "10"
},
{
"name": "type",
"type": "string",
"required": true,
"description": "输出格式。json=完整信息(默认) / text=纯链接文本 / mp3=302跳转到音频",
"example": "json"
}
]
{
"openapi": "3.1.1",
"info": {
"title": "黄盒音乐",
"description": "使用某黄盒官方提供的官方API进行获取的数据",
"version": "1.0.0"
},
"paths": {
"/api/yinyue/kuwo/api.php": {
"get": {
"summary": "黄盒音乐",
"description": "使用某黄盒官方提供的官方API进行获取的数据",
"parameters": [
{
"name": "key",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "接口调用密钥"
},
{
"name": "msg",
"in": "query",
"required": true,
"schema": {
"type": "string",
"example": "江南"
},
"description": "搜索的歌名(必填,不传或为空时返回错误)"
},
{
"name": "n",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "选第几首(1-based)。不传或为空 => 列表模式;1=第1首,2=第2首,以此类推"
},
{
"name": "br",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "音质数字，对应规格如下"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "搜索页码,默认1"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "10"
},
"description": "每页数量,默认10"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"example": "json"
},
"description": "输出格式。json=完整信息(默认) / text=纯链接文本 / mp3=302跳转到音频"
}
],
"responses": {
"200": {
"description": "成功",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
},
"post": {
"summary": "黄盒音乐",
"description": "使用某黄盒官方提供的官方API进行获取的数据",
"parameters": [
{
"name": "key",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "接口调用密钥"
},
{
"name": "msg",
"in": "query",
"required": true,
"schema": {
"type": "string",
"example": "江南"
},
"description": "搜索的歌名(必填,不传或为空时返回错误)"
},
{
"name": "n",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "选第几首(1-based)。不传或为空 => 列表模式;1=第1首,2=第2首,以此类推"
},
{
"name": "br",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "音质数字，对应规格如下"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "1"
},
"description": "搜索页码,默认1"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "10"
},
"description": "每页数量,默认10"
},
{
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"example": "json"
},
"description": "输出格式。json=完整信息(默认) / text=纯链接文本 / mp3=302跳转到音频"
}
],
"responses": {
"200": {
"description": "成功",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
}
},
"servers": [
{
"url": "https://api.317ak.com",
"description": "当前访问入口（https）"
}
]
}
返回示例
{
"al_name": "第二天堂",
"ar_name": "林俊杰",
"level": "标准音质",
"name": "江南",
"pic": "http://img1.kwcdn.kuwo.cn/star/albumcover/500/s4s60/86/1922632933.jpg",
"size": "4.09MB",
"status": 200,
"tlyric": "",
"url": "http://other-er.kuwo.cn/4a12162e504cc8f5fd7b785577e97c4f/6a0f3afe/resource/30106/trackmedia/M500004TXEXY2G2c7C.mp3",
"lyric": "[00:00.000] 江南 - 林俊杰 (JJ Lin)\n[00:09.280] 词：李瑞洵\n[00:18.560] 曲：林俊杰\n[00:27.850] 编曲：蔡政勋/陈建玮\n[00:37.130] 风到这里就是黏\n[00:40.560] 黏住过客的思念\n[00:45.030] 雨到了这里缠成线\n[00:48.680] 缠着我们留恋人世间\n[00:53.020] 你在身边就是缘\n[00:56.540] 缘分写在三生石上面\n[01:01.070] 爱有万分之一甜\n[01:04.580] 宁愿我就葬在这一点\n[01:08.900] 圈圈圆圆圈圈\n[01:10.870] 天天年年天天的我\n[01:13.720] 深深看你的脸\n[01:16.020] 生气的温柔\n[01:18.050] 埋怨的温柔的脸\n[01:24.170] 不懂爱恨情愁煎熬的我们\n[01:27.800] 都以为相爱就像风云的善变\n[01:32.000] 相信爱一天抵过永远\n[01:36.730] 在这一刹那冻结了时间\n[01:40.260] 不懂怎么表现温柔的我们\n[01:43.940] 还以为殉情只是古老的传言\n[01:48.090] 离愁能有多痛痛有多浓\n[01:52.340] 当梦被埋在江南烟雨中\n[01:55.560] 心碎了才懂\n[02:21.270] 圈圈圆圆圈圈\n[02:22.810] 天天年年天天的我\n[02:25.850] 深深看你的脸\n[02:28.110] 生气的温柔\n[02:30.200] 埋怨的温柔的脸\n[02:36.080] 不懂爱恨情愁煎熬的我们\n[02:39.840] 都以为相爱就像风云的善变\n[02:43.910] 相信爱一天抵过永远\n[02:48.240] 在这一刹那冻结了时间\n[02:52.200] 不懂怎么表现温柔的我们\n[02:55.810] 还以为殉情只是古老的传言\n[02:59.970] 离愁能有多痛痛有多浓\n[03:04.340] 当梦被埋在江南烟雨中\n[03:07.620] 心碎了才懂\n[03:20.130] 相信爱一天抵过永远\n[03:24.400] 在这一刹那冻结了时间\n[03:28.510] 不懂怎么表现温柔的我们\n[03:32.150] 还以为殉情只是古老的传言\n[03:36.210] 离愁能有多痛痛有多浓\n[03:40.390] 当梦被埋在江南烟雨中\n[03:45.690] 心碎了才懂"
}
详细文档
黄盒音乐
接口说明
黄盒音乐接口用于获取音乐相关数据，方便开发者通过接口接入音乐查询能力。
该接口面向需要音乐检索与信息获取的应用场景使用。
调用地址
https://api-v2.317ak.com/api/yinyue/kuwo/api.php
请求方式
GET, POST
鉴权说明
本接口调用需要密钥。
首选鉴权方式：Query 参数鉴权。
请求时需携带 key=… 参数完成鉴权。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 接口调用密钥，通过 Query 参数 key 传递。 |
| msg | string | 是 | 搜索的歌名，不传或为空时返回错误。示例：江南 |
| n | string | 否 | 选择第几首歌曲（1-based）。不传或为空时返回列表模式；填写 1 表示第 1 首，填写 2 表示第 2 首，以此类推。示例：1 |
| br | string | 否 | 音质规格选择参数。示例：1 |
| page | string | 否 | 搜索页码，默认值为 1。示例：1 |
| limit | string | 否 | 每页返回数量，默认值为 10。示例：10 |
| type | string | 是 | 输出格式。json：返回完整信息；text：返回纯链接文本；mp3：返回音频跳转。默认输出格式为 json。示例：json |
成功响应示例
请求成功时返回歌曲详细信息，例如：
{
"al_name": "第二天堂",
"ar_name": "林俊杰",
"level": "标准音质",
"name": "江南",
"pic": "http://img1.kwcdn.kuwo.cn/star/albumcover/500/s4s60/86/1922632933.jpg",
"size": "4.09MB",
"status": 200,
"tlyric": "",
"url": "http://other-er.kuwo.cn/4a12162e504cc8f5fd7b785577e97c4f/6a0f3afe/resource/30106/trackmedia/M500004TXEXY2G2c7C.mp3",
"lyric": "[00:00.000] 江南 - 林俊杰 (JJ Lin)\n[00:09.280] 词：李瑞洵\n[00:18.560] 曲：林俊杰"
}响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| al_name | string | 专辑名称 |
| ar_name | string | 歌手名称 |
| level | string | 音质信息 |
| name | string | 歌曲名称 |
| pic | string | 歌曲封面地址 |
| size | string | 音频文件大小 |
| status | number | 请求状态标识 |
| tlyric | string | 翻译歌词内容 |
| url | string | 音频播放地址 |
| lyric | string | 歌词内容 |
错误响应示例
当接口请求失败时，返回统一 JSON 格式：
{
"code":0,
"msg":"未提供调用密钥",
"errcode":11001
}业务错误码说明
| errcode | 含义 |
|---|---|
| 11001 | 未提供调用密钥 |
| 11002 | 密钥错误 |
| 11003 | 密钥已禁用 |
| 11004 | 积分余额不足 |
| 11005 | 请求过于频繁（QPM 限制） |
| 11006 | 接口维护中 |
| 11007 | 接口已禁用 |
| 11008 | 接口不可用 |
| 11009 | 密钥校验暂不可用 |
| 11010 | 积分系统暂不可用 |
| 11011 | 收费接口须提供有效密钥 |
| 11012 | 鉴权方式错误 |
| 11013 | 接口不存在 |
| 11014 | 地址无效 |
| 11015 | 地址不允许 |
| 11016 | 请求失败 |
| 11017 | 服务暂不可用 |
| 11018 | 请求方式不允许 |
| 11019 | 当前IP不在白名单内 |
| 11020 | 启用相关功能须提供有效密钥 |
| 11021 | 未配置可用服务 |
| 11022 | 服务不可用 |
| 11023 | 密钥已过期 |
| 11024 | 令牌分配积分不足 |
调用示例
终端 curl（bash）
curl -G 'https://api-v2.317ak.com/api/yinyue/kuwo/api.php' \
--data-urlencode 'key=YOUR_API_KEY' \
--data-urlencode 'msg=江南' \
--data-urlencode 'n=1' \
--data-urlencode 'br=1' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=10' \
--data-urlencode 'type=json'PHP
// PHP
$url = 'https://api-v2.317ak.com/api/yinyue/kuwo/api.php?'. http_build_query([
'key' => 'YOUR_API_KEY',
'msg' => '江南',
'n' => '1',
'br' => '1',
'page' => '1',
'limit' => '10',
'type' => 'json',
]);
$response = file_get_contents($url);
echo $response;注意事项
- 请妥善保管接口调用密钥
key，避免泄露或公开发布。密钥应仅用于服务端调用，不建议直接嵌入网页前端、客户端代码或公开仓库中。 - 本接口请求必须携带有效密钥，使用 Query 参数
key进行鉴权。密钥错误、缺失或无效时，请求可能无法正常返回数据。 - 请求时请确保
msg参数有有效内容。搜索歌名为空或未传入时会返回错误结果。 n参数用于选择搜索结果中的指定歌曲，采用从 1 开始计数的方式填写；不填写时返回搜索列表。page与limit用于分页查询，未设置时分别默认为第 1 页和每页 10 条数据。大量查询时建议合理控制分页范围。br参数用于指定音质规格，请根据实际需求填写对应值，避免传入不支持的参数值导致返回异常。type参数决定返回格式，请根据业务场景选择json、text或mp3。需要完整歌曲信息时建议使用json格式。- 建议使用 HTTPS 方式请求接口，保护请求过程中的参数信息安全。
- 请根据实际业务场景控制请求频率，避免短时间内大量重复请求影响接口稳定性。
快速上手
curl -G "https://api-v2.317ak.com/api/yinyue/kuwo/api.php" \
--data-urlencode "key=YOUR_API_KEY" --data-urlencode "msg=江南" \
--data-urlencode "type=json" --data-urlencode "n=1"在线测试
请求地址
api.317ak.com/api/yinyue/kuwo/api.php
Method
参数
Response
// 结果将在此处显示
