# 网易云音乐 榜单 API (netease_music.toplist)

- Canonical page: [https://everyinfra.com/netease-music-api/toplist](https://everyinfra.com/netease-music-api/toplist?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "netease_music", "action": "toplist", "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

网易云音乐榜单读取网易云官方发布的榜单，不需要任何参数。每行是榜单上的一首歌：名次、歌名与别名、歌手、专辑与封面、时长、发行时间、是否含限制级内容和网易云热度分，并附所属榜单的名称、ID、封面、播放量、收藏数和最近更新时间。它回答「网易云上现在哪些歌排在前面」，适合做榜单报告、音乐营销和艺人发掘，也适合捕捉正在上升的歌曲。

`popularity_score` 是网易云的热度分，范围 0 到 100，不是播放次数；`duration_ms` 的单位是毫秒，除以 1000 才是秒。榜单变化快，存档时保留每行的 `snapshotted_at`，比较不同批次时以它为准。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| 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": "toplist",
  "params": {}
}'
```

```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": "toplist",
        "params": {},
    },
    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": "toplist",
  "results": [
    {
      "rank": 1,
      "track_id": 3425638996,
      "track_name": "互删 (我走以后)",
      "duration_ms": 211686,
      "artists": "江辰",
      "artist_ids": "12641765",
      "album_id": 394443308,
      "album_name": "互删 (我走以后)",
      "album_cover_url": "http://p3.music.126.net/nfDVr6WopOJax11vq5brPQ==/109951173820334666.jpg",
      "published_at": "2026-08-28T16:00:00+00:00",
      "is_explicit": false,
      "popularity_score": 100,
      "track_url": "https://music.163.com/song?id=3425638996",
      "playlist_id": 3779629,
      "playlist_name": "飙升榜",
      "playlist_type": "toplist",
      "playlist_cover_url": "https://p4.music.126.net/5guhqPBTcIrrhLBotgaT6w==/109951170048511751.jpg",
      "playlist_track_count": 100,
      "playlist_play_count": 3218496768,
      "playlist_subscribed_count": 2805127,
      "playlist_updated_at": "2026-09-26T04:32:03.946000+00:00",
      "snapshotted_at": "2026-09-26T09:57:26.623000+00:00",
      "platform": "netease_music"
    },
    {
      "rank": 2,
      "track_id": 3433437362,
      "track_name": "两难pt.2",
      "duration_ms": 259956,
      "artists": "加木",
      "artist_ids": "49320722",
      "album_id": 397217802,
      "album_name": "两难pt.2",
      "album_cover_url": "http://p3.music.126.net/jr4V-LHARj4EGtLeDCLB_Q==/109951173909480514.jpg",
      "is_explicit": false,
      "popularity_score": 100,
      "track_url": "https://music.163.com/song?id=3433437362",
      "playlist_id": 3779629,
      "playlist_name": "飙升榜",
      "playlist_type": "toplist",
      "playlist_cover_url": "https://p4.music.126.net/5guhqPBTcIrrhLBotgaT6w==/109951170048511751.jpg",
      "playlist_track_count": 100,
      "playlist_play_count": 3218496768,
      "playlist_subscribed_count": 2805127,
      "playlist_updated_at": "2026-09-26T04:32:03.946000+00:00",
      "snapshotted_at": "2026-09-26T09:57:26.625000+00:00",
      "platform": "netease_music"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 能指定读取哪个榜单吗？

不能，这个能力没有参数，返回网易云公布的官方榜单；每行的 `playlist_name` 和 `playlist_id` 说明它属于哪个榜。要读其他公开歌单，把歌单数字 ID 或歌单链接交给网易云音乐的播放列表能力。

### 榜单数据是什么时候的？

每行带两个时间：`playlist_updated_at` 是网易云最近一次更新这个榜单的时间，引用榜单日期时用它；`snapshotted_at` 是这一行被读取的时刻，用来标明你的存档取自何时。

### 怎么计算一首歌的名次升降？

定时读取榜单，按 `track_id` 记录每次的 `rank` 和 `snapshotted_at`，并只在同一个 `playlist_id` 内比较。两次之间名次的差就是升降幅度；第一次出现的 `track_id` 是新上榜，之后不再出现的就是掉出了榜单。

## 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
