流云音乐 - 推送 API 文档

发布于 2026-07-14 · 流云音乐

基础信息

项目内容
服务地址https://api.pyzo.top
请求方式POST
数据格式JSON
💡 提示所有请求需设置请求头 Content-Type: application/json。

1. 注册设备

POST /register

参数必填说明
userId✅ 必填设备 UUID
deviceToken不填APNs 令牌（64位十六进制）
curl -X POST https://api.pyzo.top/register \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","deviceToken":"你的设备令牌"}'

2. 查询设备

GET /api/user?userId={userId}

curl "https://api.pyzo.top/api/user?userId=你的设备ID"

3. 发送推送

POST /send

参数必填说明
userId✅ 必填设备 ID
isSilent可选是否静默推送（默认 false）
title可选通知标题（静默时无效）
body可选通知内容（静默时无效）
type可选指令类型（见下表）
# 普通推送（显示通知）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","title":"流云音乐","body":"🎵 测试消息","type":"notice","isSilent":false}'

# 静默推送（不显示通知）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","type":"next_song","isSilent":true}'

4. 播放控制

以下接口均为静默推送，不显示通知横幅：

功能接口type额外参数
⏸️ 播放/暂停/api/toggle_playtoggle_play-
⏭️ 下一首/api/next_songnext_song-
⏮️ 上一首/api/previous_songprevious_song-
❤️ 切换喜欢/api/like_songlike_song-
🎲 随机播放/api/randomplay_random-
❤️ 播放喜欢列表/api/likedplay_liked-
🎵 按歌名播放/api/play_by_nameplay_song_by_namesongTitle
🎤 按歌手播放/api/play_singerplay_singersingerName
📁 播放歌单/api/play_playlistplay_playlistplaylistName
# 下一首（静默）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","type":"next_song","isSilent":true}'

# 播放/暂停（静默）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","type":"toggle_play","isSilent":true}'

# 按歌名播放（静默）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","type":"play_song_by_name","isSilent":true,"customData":{"songTitle":"七里香"}}'

5. 歌曲同步

以下接口均为静默推送：

功能接口type说明
🧠 智能同步/api/sync/smartsync_smart按播放次数优先（默认1000首）
📦 全量同步/api/sync/fullsync_full同步所有歌曲（耗时较长）
📥 增量同步/api/sync/incrementalsync_incremental只同步最近添加（默认1000首）
# 智能同步（静默）
curl -X POST https://api.pyzo.top/send \
  -H "Content-Type: application/json" \
  -d '{"userId":"你的设备ID","type":"sync_smart","isSilent":true,"customData":{"count":200}}'

6. 静默推送说明

🔇 静默推送
  • App 必须在后台运行，被杀死后无效
  • 不会显示通知横幅
  • 有频率限制（约每小时数十次）
  • 适合播放控制、同步等后台任务

7. 测试接口

接口说明
GET /test健康检查
GET /webWeb 控制台
curl https://api.pyzo.top/test

支持的指令类型

type说明默认标题默认内容
toggle_play播放/暂停⏸️ 播放控制播放状态已切换
next_song下一首⏭️ 下一首正在播放下一首
previous_song上一首⏮️ 上一首正在播放上一首
like_song切换喜欢❤️ 切换喜欢已切换喜欢状态
play_random随机播放🎲 随机播放开始随机播放
play_liked播放喜欢列表❤️ 喜欢的歌曲播放你喜欢的歌曲
play_song_by_name按歌名播放🎵 播放歌曲正在搜索并播放
play_singer按歌手播放🎤 歌手歌曲正在搜索歌手歌曲
play_playlist播放歌单📁 播放歌单正在播放歌单
sync_smart智能同步🧠 智能同步开始智能同步
sync_full全量同步📦 全量同步开始全量同步
sync_incremental增量同步📥 增量同步开始增量同步
notice普通通知📢 通知来自流云音乐的通知
music_update音乐更新🎵 音乐更新你有一首新歌推荐！

响应格式

成功：

{
  "success": true,
  "message": "指令已发送",
  "userId": "FA8CAD65-2186-4B3C-B3FE-783D9D87D000"
}

失败：

{
  "success": false,
  "error": "User not registered for push"
}

常见问题