---
title: "曲库标签分类聚合"
method: GET
path: "/songs/facets"
tags: ["歌曲管理"]
---

# 曲库标签分类聚合

`GET /songs/facets`

按指定维度聚合曲库，返回该维度下非空取值、各自的歌曲数量及一首代表歌曲的封面 URL，用于「分类浏览」的卡片网格。
支持维度：genre(流派)/artist(歌手)/album(专辑)/language(语种)/style(风格)/year(年份)/decade(年代)。
year/decade 的 value 为数字字符串（年代如 "1990" 表示 1990-1999）。取到某取值后可用 /songs?<field>=<value> 拉取该分类下歌曲。
支持 keyword 模糊搜索取值、limit/offset 分页、sort(count|name)/order 排序；返回 total 为该维度去重取值总数。

## Query parameters

- `field` 'genre' | 'artist' | 'album' | 'language' | 'style' | 'year' | 'decade', required
- `keyword` string
- `limit` integer
- `offset` integer
- `sort` 'count' | 'name'
- `order` 'asc' | 'desc'

## Response `200`

成功返回聚合结果 {field, facets:[{value,count,cover_url}], total, limit, offset}

- object

## Other responses

- `400` — 缺少或不支持的 field
- `500` — 服务器错误

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/versions/77467de6ed1b/schema)