开放接口文档

本服务对外提供三大音源（网易云、QQ、酷狗）的标准化访问能力，包含以下 6 项能力：

本接口采用域名白名单鉴权，无需 API Key。调用方网站域名需由服务端管理员预先加入白名单，明明主页设计的网站（同源调用）默认放行，无需加入白名单。

服务端会自动读取请求中的 Origin 或 Referer HTTP 头来识别调用方域名，按以下优先级校验：

1. 同源放行：调用方域名 = 本站域名（如明明主页设计的网站 /page/* 调用本站接口），自动通过
2. 本地放行：localhost / 127.0.0.1（本地开发环境）自动通过
3. 白名单校验：其他外部域名必须在白名单内才能调用

{"code": -1, "error": "域名未授权: your-domain.com"}

服务端已开启 CORS，允许浏览器直接跨域调用。响应头包含：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type

对于 OPTIONS 预检请求，服务端会直接返回 204 No Content。

为保障服务稳定性，开放接口对每个调用方 IP 进行限流。注意：限流的是接口调用次数，不是播放歌曲数。正常播放一首歌仅需 2-4 次调用（搜索 + 获取地址 + 可选歌词/封面），实际听歌完全不受影响。

{"code": -1, "error": "请求过于频繁，请稍后再试"}

建议客户端实现请求队列和缓存（搜索结果可缓存 10-30 分钟，播放地址可缓存 1 小时），加了缓存后重复播放同一首歌不消耗调用次数。

POST /api/open/music/search HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=周杰伦&type=wy&page=1&limit=30&format=1

{
  "code": 1,
  "data": [
    {
      "id": "186016",
      "name": "晴天",
      "artist": "周杰伦",
      "album": "叶惠美",
      "pic_id": "186016",
      "url_id": "186016",
      "lyric_id": "186016",
      "sign": ""
    }
  ]
}

{
  "code": 1,
  "data": {
    "url": "https://xxxcdn.com/xxx.mp3"
  }
}

{
  "code": 1,
  "data": {
    "lyric": "[00:12.00]故事的小黄花 [00:15.00]从出生那年就飘着...",
    "tlyric": ""
  }
}

{
  "code": 1,
  "data": {
    "url": "https://p1.music.126.net/xxx.jpg"
  }
}

返回的 URL 可直接用于 <img> 标签的 src。

返回歌单内的全部歌曲列表，字段结构与搜索接口一致（含 songId、songName、artistName、albumName、albumCover 等并行数组）。

{
  "playlist": [
    {
      "id": "123456",
      "name": "我喜欢的音乐",
      "coverImgUrl": "https://xxx.jpg",
      "creator": {
        "nickname": "用户昵称",
        "avatarUrl": "https://xxx.jpg"
      }
    }
  ]
}

{
  "code": -1,
  "error": "错误描述信息"
}

// 1. 搜索歌曲
async function searchSongs(keyword) {
  const params = new URLSearchParams({
    name: keyword,
    type: 'wy',       // wy=网易云 qq=QQ音乐 kg=酷狗
    page: '1',
    limit: '30',
    format: '1'
  })
  const res = await fetch('https://your-domain.com/api/open/music/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: params.toString()
  })
  const data = await res.json()
  return data.code === 1 ? data.data : []
}

// 2. 获取播放地址
async function getPlayUrl(songId, type, sign) {
  const params = new URLSearchParams({ id: songId, type })
  if (sign) params.append('sign', sign)
  const res = await fetch('https://your-domain.com/api/open/music/url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: params.toString()
  })
  const data = await res.json()
  return data.code === 1 ? data.data.url : ''
}

// 3. 完整流程：搜索 → 播放
;async function playSong(keyword) {
  const songs = await searchSongs(keyword)
  if (songs.length === 0) return

  const song = songs[0]
  const url = await getPlayUrl(song.url_id, 'wy', song.sign)
  if (url) {
    const audio = new Audio(url)
    audio.play()
  }
}

<?php
function searchMusic($keyword, $type = 'wy') {
    $url = 'https://your-domain.com/api/open/music/search';
    $data = http_build_query([
        'name' => $keyword,
        'type' => $type,
        'page' => 1,
        'limit' => 30,
        'format' => 1
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $data,
        CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10
    ]);
    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

$result = searchMusic('周杰伦');
print_r($result);

import requests

def search_songs(keyword, source='wy'):
    url = 'https://your-domain.com/api/open/music/search'
    data = {
        'name': keyword,
        'type': source,
        'page': 1,
        'limit': 30,
        'format': 1
    }
    resp = requests.post(url, data=data, timeout=10)
    return resp.json()

result = search_songs('周杰伦')
print(result)

联系服务端管理员，在管理后台「接口」菜单中添加您的域名即可。添加后立即生效，无需重启服务。

可以。localhost / 127.0.0.1 已默认放行，无需加入白名单。但浏览器在 localhost 环境可能不发送 Origin 头，会改用 Referer 识别。

常见原因：① VIP 付费歌曲；② 因版权下架；③ 地区限制。这是上游音源的限制，非接口问题。

有。不同音源的 CDN 地址有效期不同，通常 30 分钟到数小时不等。建议每次播放时实时获取，不要长期缓存播放地址。

525 表示上游音乐服务暂时不可用（SSL 握手失败），通常是上游服务器临时故障，稍后重试即可。

在网易云/QQ/酷狗的网页版或客户端打开歌单，URL 中的数字 ID 即为歌单 ID。例如 music.163.com/#/playlist?id=3778678 的歌单 ID 是 3778678。