---
title: "曲库筛选词表 / Faceted vocabulary"
method: POST
path: "/agent/v1/km_vocabulary"
---

# 曲库筛选词表 / Faceted vocabulary

`POST /agent/v1/km_vocabulary`

## Request

- Base URL: `https://share.kindlemusic.cn`
- URL: `https://share.kindlemusic.cn/agent/v1/km_vocabulary`
- Auth: one of:
  - none
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://share.kindlemusic.cn/oauth/authorize`, token URL `https://share.kindlemusic.cn/oauth/token`)

列出曲库全部可用的筛选值（流派/情绪/乐器/速度/适用场景/厂牌）。
Lists every filterable facet value in the catalog (genre, mood, instrumentation, tempo, music-for, label).

何时用 / When: 在 km_search 里使用任何 include*/exclude* 筛选之前，先用本工具确认取值。
Call this BEFORE using any include*/exclude* filter in km_search.

入参 / Args: field（可选，facet 字段名子串，如 "genre"/"mood"/"library"）；query（可选，对取值与中文名做不区分大小写的子串过滤，中文也能查，如 query="悲伤"）。

返回 / Returns: 每个 facet 字段的 { param, values }，values 里每项是 { value, labelZh, count }。param 就是 km_search 里该字段对应的入参名。
顶层另有 labels[]：320 个厂牌的 { library_name, library_type, company, album_count, track_count }，可用来判断某个厂牌值不值得单独收窄。
⚠️ value 必须**原样**回填到 km_search，不要翻译、改大小写或去掉 "Parent;Leaf" 里的分号；改动过的值一律匹配不上。labelZh 只供你把中文 brief 映射到 canonical 值，不要回填。
count 用来防过度收窄：候选值 count < 200 时考虑放宽或换父级（例：`sad` 有 8.6 万首，而叶子 `sad;breakup` 只有 38 首，直接用叶子会把结果掐死）。

## Request body

- object
  - `field` string: Substring of a facet field name, e.g. "genre", "mood", "instrumentation", "library".
  - `query` string: Case-insensitive substring filter applied to the facet values and their Chinese labels.

## Response `200`

tool 结果（与 MCP tools/call 返回的 JSON 相同）

- object

## Other responses

- `400`: 入参错误或 km 业务错误：{ error, message, hint? } / { error:"km_error", code, message }
- `401`: 需要 scope 的 tool 缺少或带了无效凭据

---

[API](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api.md) · [All operations](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api/revisions/2673f364b5b0?raw)