为了确保您的开发体验，建议您使用Apifox浏览器插件或客户端进行调试。

实时歌词更新事件

Webhook

POST

lyric_update

最后修改时间：2026-08-07 18:27:54

歌词行发生变化时推送。连接建立时，若已有缓存的歌词则补发一次，否则不发。

index: -1 纯音乐说明：
当平台未返回任何歌词数据时，发送 index: -1。此时 data 不为 {}，而是包含完整字段的对象：timestamp: 0、sub_text: ""，而 progress 照常反映播放进度；text 不保证为空（cloudmusicv3 / kugou 保留平台提示语「纯音乐，请欣赏」，qqmusic 与 sodamusic 为 ""）。
与此同时会发送一条 all_lyrics（count: 0，lyrics: []）。
客户端利用 msg.data.index === -1 识别纯音乐。

请求参数

Body 参数application/json必填

示例

有歌词时无歌词时平台未返回可用歌词。kugou / cloudmusicv3 对纯音乐会返回一行「纯音乐，请欣赏」，服务端把 index 归一为 -1 但保留该文本；qqmusic 返回零行、sodamusic 平台

{
    "type": "lyric_update",
    "player": "wesing",
    "data": {
        "index": 1,
        "text": "往事就像流星刹那划过心房",
        "sub_text": "",
        "timestamp": 31.483,
        "play_time": 31.282999,
        "position": 31.282999,
        "progress": 0.105743244,
        "text_detailed": {}
    }
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

cURL

curl --location 'https://your-api-server.com' \
--header 'Content-Type: application/json' \
--data '{
    "type": "lyric_update",
    "player": "wesing",
    "data": {
        "index": 1,
        "text": "往事就像流星刹那划过心房",
        "sub_text": "",
        "timestamp": 31.483,
        "play_time": 31.282999,
        "position": 31.282999,
        "progress": 0.105743244,
        "text_detailed": {}
    }
}'

返回响应

🟢200

事件已接收

该响应没有 Body

歌曲信息更新事件

完整歌词列表事件