QQ Music Official Intelligent Assistant

Call QQ Music Open Platform APIs via Agent Gateway to provide capabilities such as search, recommendation, music charts, playlists, etc.

Supported Capabilities

Capability	Description	User Example	Detailed Guide
Search	Search songs, albums, playlists, MVs, radio stations, artists	"Help me search for Jay Chou" "Search for the song 'Sunny Day'"	`discover.md`
Daily Recommendations	30 personalized daily recommendations	"What songs are recommended today?"	`discover.md`
Recommended for You	Recommended for You Radio	"Recommend some songs I might like"	`discover.md`
AI Playlists	AI-recommended playlists	"Recommend some running playlists"	`discover.md`
Music Charts	View various music charts	"Check the music charts"	`charts.md`
Playlist Details	View the complete song list of a playlist	"What's in this playlist?"	`playlists.md`
Listening Reports	Aggregated listening statistics by day/week/month	"Today's listening report" "How much did I listen this week?"	`me.md`
AI Interpretation	Interpretation based on your QQ Music journey, only call this interface when the user explicitly requests interpretation	"Analyze my listening style" "What kind of listener am I?" "Recommend 10 songs based on my listening history"	`assistant.md`
Skill Upgrade	Check for skill version updates and automatically download and replace with the latest version	"Update QQ Music skill" "Upgrade QQ Music skill" "Check if there's a new version of QQ Music"	`version.md`

Before calling any API, you must first read the corresponding capability guide (such as discover.md, me.md) to confirm the API parameters and field meanings before making the call. Do not guess based solely on field names.

Route Priority (Important)

Structured APIs take priority, AI Interpretation is the fallback. First determine if the user's intent matches any of the first 7 capabilities (Search/Daily Recommendations/Recommended for You/AI Playlists/Music Charts/Playlist Details/Listening Reports). If it matches, use the corresponding API; only use AI Interpretation when the user explicitly requests "analysis/interpretation/profile" (e.g., "Analyze my listening style", "What kind of listener am I?").

Common Misjudgment Scenarios:

"Recommend some songs", "Recommend xx for me" → Use Daily Recommendations/Recommended for You/AI Playlists, do not use AI Interpretation
"What did I listen to today", "Listening report" → Use
```
/me/report
```
, do not use AI Interpretation
"Search for xx" → Use
```
/discover/search
```
, do not use AI Interpretation

API Calling Specifications

Unified Entry

text

POST ${BaseUrl}{path}

```
BaseUrl
```
defaults to
```
https://a.y.qq.com
```
```
{path}
```
is the specific API path, such as
```
/discover/search
```
,
```
/discover/daily-mix
```
etc. See the respective capability guides for details

Authentication

Header:
```
Authorization: Bearer $QQMUSIC_API_KEY
```
API Key format is
```
qmk-xxxxxxxx
```
, bound to the user account. APIs requiring user identity will automatically identify the caller
Obtain API Key: https://y.qq.com/n/ryqq_v2/qqmusic_skills
Authentication depends on the environment variable
```
$QQMUSIC_API_KEY
```

Key Initialization Process (For first use or when Key is not set):

First execute
```
echo $QQMUSIC_API_KEY
```
to check if it is already set
If set, use it directly and skip the subsequent steps
If not set, actively ask the user to provide the Key
After the user provides it, detect the current Shell type and write
```
export QQMUSIC_API_KEY="<API Key>"
```
to the corresponding profile:
- bash →
```
~/.bashrc
```
- zsh →
```
~/.zshrc
```
- Before writing, check if there is an old QQMUSIC_API_KEY configuration; if so, replace it
After writing, execute
```
source <profile file>
```
to make it take effect immediately, then proceed with subsequent calls

Request Format

Method: POST
Content-Type: application/json
Body: JSON,
```
params
```
stores business parameters,
```
comm
```
stores public parameters, comm.skill_version
must be included in every request

bash

curl -X POST "${BaseUrl}/discover/search" \
  -H "Authorization: Bearer $QQMUSIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"keyword": "周杰伦", "type": "0"}, "comm": {"skill_version": "0.0.2"}}'

Field	Type	Required	Description
`params`	object	Yes	Business parameters, see respective capability guides for specific fields
`comm`	object	Yes	Public parameters
`comm.skill_version`	string	Yes	Current SKILL version number, take the `version` field at the top of this file

Request Method

Correct: Business parameters are wrapped in
params
,
comm.skill_version
is at the same level.

json

{
  "params": {
    "keyword": "周杰伦",
    "type": "0"
  },
  "comm": {
    "skill_version": "0.0.2"
  }
}

Incorrect: Business parameters are placed at the top level without
params
wrapping.

json

{
  "keyword": "周杰伦",
  "type": "0",
  "skill_version": "0.0.2"
}

The incorrect writing above will cause downstream services to not receive any business parameters and return default values.

Response Format

All API responses include public fields + business fields, placed at the top level. Take search as an example:

json

{
  "traceId": "61f801eb3f0d5420",
  "ts": 1780035265227,
  "songs": [
    {
      "songMid": "0039MnYb0qxYhV",
      "songName": "晴天",
      "songH5Url": "https://y.qq.com/n/ryqq/songDetail/0039MnYb0qxYhV",
      "singerName": "周杰伦"
    },
    ...
  ],
  "albums": null,
  "playlists": null,
  "mvs": null,
  "radios": null,
  "singers": null
}

Field	Description
`traceId`	Full-link tracking ID
`ts`	Response timestamp (milliseconds)
`ret`	Gateway layer error code; a non-zero value indicates an exception
`sub_ret`	Business layer error code; a non-zero value indicates an exception
`msg`	Error description
Business Fields	Such as `songs` , `songlist` etc., placed at the same level as public fields. See respective capability guides for details

General Rules

Version Reporting: Every request must carry
```
"skill_version": "0.0.2"
```
in
```
comm
```
(take the value of the
```
version
```
field at the top of this file)
Parameter Wrapping: Business parameters must be placed inside the
```
params
```
object; only public parameters are placed in
```
comm
```
.
Capability Guide Pre-check: Before calling any API, you must first read the corresponding guide according to the "Supported Capabilities" table to confirm API parameters and field meanings; do not guess based solely on field names.
Result Display: Display lists with numbers; display songs with song name + singer; attach a "Play" link when there is an H5 link. See respective capability guides for the output format of each capability.
Context Continuity: Remember the queried songs and singers during the conversation; no need to provide them repeatedly in subsequent operations.
Prohibit Inline Key: All curl commands must use the
$QQMUSIC_API_KEY
environment variable; it is strictly forbidden to include the actual Key value in the curl command line (e.g.,
```
-H "Authorization: Bearer qmk-xxx"
```
). Writing the Key to the Shell profile is a one-time initialization operation and is not restricted by this rule.

Usage Restrictions

Rate Limiting: APIs have QPS limits. Do not call them continuously at high frequency in loops. If a rate-limiting error is returned, wait and retry.
Data Privacy: APIs such as
```
/me/report
```
return your personal listening data (listening habits, preferred genres, etc.). Do not share the results with untrusted third parties.
Usage Restrictions: This skill is for personal music query and experience only. It is prohibited to use it for unauthorized scenarios such as bulk crawling of music libraries, data mining, commercial analysis, etc. If abuse is detected, the server reserves the right to revoke the API Key.

Skill Upgrade

It is recommended to check for upgrades at least once a week. See version.md for details

H5 Link Splicing

When there is an H5 link in the API response, use the one in the response first; When there is no H5 link in the API response, you can automatically splice it according to the following rules:

Song:
```
https://i2.y.qq.com/a/song/{songMid}
```
Album:
```
https://i2.y.qq.com/a/album/{albumMid}
```

Singer:

https://i2.y.qq.com/a/singer/{singerMid}

MV:
```
https://i2.y.qq.com/a/mv/{mvVid}
```
Playlist:
```
https://i2.y.qq.com/a/playlist/{dissId}
```
Music Chart:
```
https://i2.y.qq.com/a/toplist/{topId}
```
Radio Station:
```
https://i2.y.qq.com/a/album/{albumMid}
```

qqmusic

NPX Install

Tags

SKILL.md Content (Chinese)

QQ Music Official Intelligent Assistant

Supported Capabilities

Route Priority (Important)

API Calling Specifications

Unified Entry

Authentication

Request Format

Request Method

Response Format

General Rules

Usage Restrictions

Skill Upgrade

H5 Link Splicing