# 网易云音乐 播放列表 API (netease_music.playlist)

- Canonical page: [https://everyinfra.com/netease-music-api/playlist](https://everyinfra.com/netease-music-api/playlist?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "netease_music", "action": "playlist", "params": {...}}
- Price: $0.000556 per call ($0.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

网易云音乐播放列表按 `playlist_id` 读出一张歌单收录的歌。每首歌一行：`track_name` 和 `track_alias` 是歌名与副标题，`artists` 是艺人，`album_name` 是专辑；歌单自身的名称、类型、曲目数和更新时间放在以 playlist 开头的几列里。它回答「这张歌单收了哪些歌」，适合拆解某个歌单的选曲思路，也适合横向比较几张同类歌单的构成。

单曲热度看 `popularity_score`，它按 0–100 打分，和整张歌单的 `playlist_play_count` 不是一回事。`album_cover_url` 是专辑封面，`playlist_cover_url` 是歌单封面，取图时别拿混。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=netease_music&action=playlist

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| playlist_id | not declared | yes | not declared | playlist 的网易云歌单数字 ID，也可传含 playlist?id= 或 /playlist/ID 的歌单链接；不是歌曲 ID。toplist 获取官方榜单，不需要此字段。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| rank | 榜单名次。 |
| track_id | 曲目 ID。 |
| track_name | 曲目名。 |
| track_alias | 曲目别名（副标题/外文名）。 |
| duration_ms | 时长，**单位毫秒**（除以 1000 才是秒）。 |
| artists | 艺人列表。 |
| artist_ids | 艺人 ID 列表。 |
| album_id | 专辑 ID。 |
| album_name | 专辑名。 |
| album_cover_url | 专辑封面。 |
| published_at | 发行时间。 |
| is_explicit | 是否含限制级内容。 |
| popularity_score | 网易云热度分，**0–100 分制**，不是播放量。 |
| track_url | 曲目链接。 |
| playlist_id | 歌单 ID。 |
| playlist_name | 歌单名。 |
| playlist_type | 歌单类型。 |
| playlist_cover_url | 歌单封面。 |
| playlist_track_count | 歌单曲目数。 |
| playlist_play_count | 歌单播放量。 |
| playlist_subscribed_count | 歌单收藏数。 |
| playlist_updated_at | 歌单最近更新时间。 |
| snapshotted_at | 该条数据的抓取时刻。榜单类数据变化快，用它判断新鲜度。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "netease_music",
  "action": "playlist",
  "params": {
    "playlist_id": "3778678"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "netease_music",
        "action": "playlist",
        "params": {
            "playlist_id": "3778678",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 20. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "netease_music",
  "action": "playlist",
  "results": [
    {
      "rank": 1,
      "track_id": 3342319503,
      "track_name": "明知故犯",
      "duration_ms": 166416,
      "artists": "Max李玄",
      "artist_ids": "57539469",
      "album_id": 357748854,
      "album_name": "失温",
      "album_cover_url": "http://p3.music.126.net/H2DFRdwP2y5SuCAn-Tuikw==/109951172568091306.jpg",
      "is_explicit": false,
      "popularity_score": 100,
      "track_url": "https://music.163.com/song?id=3342319503",
      "playlist_id": 3778678,
      "playlist_name": "原创榜",
      "playlist_type": "toplist",
      "playlist_cover_url": "https://p4.music.126.net/0SUEG8yDACfx0Bw2MYFv4Q==/109951170048519512.jpg",
      "playlist_track_count": 200,
      "playlist_play_count": 14152643584,
      "playlist_subscribed_count": 13177436,
      "playlist_updated_at": "2026-09-26T00:30:24.072000+00:00",
      "snapshotted_at": "2026-09-26T09:57:42.809000+00:00",
      "platform": "netease_music"
    },
    {
      "rank": 2,
      "track_id": 1973665667,
      "track_name": "海屿你",
      "track_alias": "求你别离开我",
      "duration_ms": 295940,
      "artists": "马也_Crabbit",
      "artist_ids": "13288861",
      "album_id": 150006421,
      "album_name": "海屿你",
      "album_cover_url": "http://p3.music.126.net/Enhy6dPn4gpyqrKhVEQvgA==/109951170483249998.jpg",
      "published_at": "2022-08-19T16:00:00+00:00",
      "is_explicit": false,
      "popularity_score": 100,
      "track_url": "https://music.163.com/song?id=1973665667",
      "playlist_id": 3778678,
      "playlist_name": "原创榜",
      "playlist_type": "toplist",
      "playlist_cover_url": "https://p4.music.126.net/0SUEG8yDACfx0Bw2MYFv4Q==/109951170048519512.jpg",
      "playlist_track_count": 200,
      "playlist_play_count": 14152643584,
      "playlist_subscribed_count": 13177436,
      "playlist_updated_at": "2026-09-26T00:30:24.072000+00:00",
      "snapshotted_at": "2026-09-26T09:57:42.810000+00:00",
      "platform": "netease_music"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `playlist_id` 可以填歌曲 ID 吗？

不可以，歌曲 ID 和歌单 ID 是两种编号，填歌曲 ID 对应不到歌单。要填的是歌单的数字 ID，例如示例里的 3778678；手里只有网页链接时，把含 playlist?id= 或 /playlist/ID 的歌单链接整条传进去，也能识别。

### 想读官方榜单该用哪一页？

用榜单那一页。它读取网易云官方发布的榜单，不需要 `playlist_id`；播放列表这一页必须带 `playlist_id`，读的是你指定的那一张歌单。两页返回的字段相同，区别只在读的是哪一份列表。

### 怎么判断读到的歌单数据新不新？

看每行的 `snapshotted_at`，它记录这条数据是什么时候抓的，数据变化快时以它判断新鲜度。`playlist_updated_at` 是歌单自己最近一次更新的时间，不是抓取时间，两个字段不要混用。比较同一张歌单两次读到的结果时，先按 `snapshotted_at` 分清批次，再看 `playlist_track_count` 有没有变。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=netease_music
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
