--- title: "曲库检索 / Search the catalog" method: POST path: "/agent/v1/km_search" --- # 曲库检索 / Search the catalog `POST /agent/v1/km_search` ## Request - Base URL: `https://share.kindlemusic.cn` - URL: `https://share.kindlemusic.cn/agent/v1/km_search` - 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`) 在 Kindle Music 正版曲库里检索曲目或专辑，支持关键词、facet 筛选、BPM 与时长区间。 Searches the Kindle Music production-music catalog: keyword + facet filters + bpm/duration ranges. searchField 怎么选 / Choosing searchField: - keywords：关键词匹配，默认值。多个词之间是 OR、按命中词数排序，所以加不同维度的词（用途 + 情绪 + 乐器）比堆近义词有用；英文加双引号是短语匹配（"epic trailer"）。不要写 AND/OR/NOT；开头的 -term 按字面匹配，不表示排除。 剧情词和抽象词（逆袭、对峙、回忆、高级感）曲库标签里很少出现，会把排序带偏：先翻译成情绪 / 乐器 / 速度这类音乐描述再检索。 expand="fast"：中文按词翻译 + 同义扩展（结果稳定，同一个词每次扩成一样）；expand="deep"：映射到曲库标准词，召回更窄、最慢约 1 分钟。不带 expand 时 keyword 必须是英文。 带 expand 时中文否定从句（不要X / 去掉X / 避免X）会从 keyword 里剥离并映射成 exclude（「不要太X」这类程度否定映射成降权），一次最多 3 条，结果见 derivedNegations。 - ai：一句自然语言描述（可中文），后端整句理解改写后检索，结果看前排而不是总数。一两个词的需求用 keywords 更好。 - semantic：text→audio 语义检索（英文效果最好），适合"听感"类描述；不可用或 0 结果时自动降级 ai。 - track：按英文原曲名查（去掉前导序号与扩展名，中文译名搜不到）。album：按专辑编号/名查，编号不区分大小写、连字符、空格与前导零。 - lyrics：按歌词查（可中文）。composer：按作曲者查（只能英文）。 - 手里是下载文件名、UPM 链接、本站链接或 PUC-045 这类编号时，先用 km_resolve 定位，不要拿它当关键词。 ⚠️ 硬约束 / Hard constraint: searchField=keywords（未带 expand）或 composer 时 keyword 只能是英文。 Passing Chinese with searchField=composer, or with keywords and no expand, is rejected up front (Solr matches literally → zero hits). 否定 / Negation: - keywords：英文的 no / without X 不会被识别（反而把 X 当正向词召回），用 exclude*；中文否定需带 expand（见上）。客户的硬性排除任何模式都用 exclude* 兜底。 - ai：直接写进句子（不要/无/别/去掉/避免 X，no/not/without X），一次最多 4 项；「不要太X」只让 X 往后排不去掉；排除后 0 结果会自动放宽。 响应里的 derivedNegations 说明每条否定被映射成了哪个 facet 值、是否被放宽——交付前核对它。 include*/exclude* 的取值必须先用 km_vocabulary 取，并原样回填。同一维度多个值是 AND（includeLabels / includeAlbums 例外，是 OR）；exclude* 命中任一即排除。 关键词不匹配厂牌名，按厂牌收窄用 includeLabels。 partition：independent = 网站「独立精选」分区，universal = 「环球UPM」分区；不传 = 两个分区合并检索（网站精选站默认只显示独立精选）。 bpmMin/bpmMax 与 durationMin/durationMax（秒）必须成对给出。 fields 怎么选 / Choosing fields: - slim（默认）：每首 25 个字段（含 track_number、四维标签 + 中英文描述 + 可播放的 url），够直接做精排与交付。pageSize 上限 50。 - compact：每首只回 10 个字段（id / album_code / track_number / track_title / track_version / track_bpm / track_duration / library_name / library_type / web_url），pageSize 上限放宽到 200。 没有"按 id 批量取全字段"的端点：compact 结果需要中文描述与四维标签时，只能对收窄后的条件重跑一次 fields=slim。 ⚠️ BPM 半速口径 / Half-time BPM: 本曲库 55/60 与 110/120 常常是同一个脉冲的两种记法（标注方按半速还是双速记没有统一）。 在架主曲落在 60–90 BPM 的有 12.6 万首，一刀切 bpmMin=95,bpmMax=125 会静默漏掉一大片听感完全对的曲子。 按 BPM 收窄时要把半速区间也检索一遍再合并，否则会漏召回。 返回 / Returns: { total, appliedSearchField, searchId, fields, tracks[]（字段集见 fields，含可直接打开的 web_url）, search_url（C 端复现本次检索的链接）}。 有扩展时另带 ai_keyword / expanded（实际检索用的英文词）；有否定时带 derivedNegations。 translation_failed:true 表示中文扩展失败、按空结果返回，不代表曲库里没有：换英文或改 searchField=ai 重试。 ai / lyrics / expand 受后端每日 LLM 配额；超额时返回 llmQuotaExceeded:true 且 appliedSearchField 降级为 keywords。 返回的 track_url 仅供试听/临时分析，见 audioNotice。 Returned track_url values are for audition / temporary analysis only; see audioNotice. ## Request body - object - `keyword` string: Query text. MUST be English for composer, and for keywords unless expand is set. - `searchField` 'keywords' | 'ai' | 'semantic' | 'album' | 'track' | 'lyrics' | 'composer': Default "keywords". Use "ai" for natural-language / Chinese briefs. - `expand` 'fast' | 'deep': keywords mode only. "fast": translate + expand Chinese per word. "deep": map to canonical catalog terms (narrower, up to ~1 min). - `view` 'tracks' | 'albums': Default "tracks". - `sort` 'relevance' | 'newest' | 'oldest' | 'duration' - `page` integer: 1-based page number, default 1. - `pageSize` integer: Default 20. Clamped to 50 with fields="slim", to 200 with fields="compact". - `fields` 'slim' | 'compact': Track field set. Default "slim" (25 fields). "compact" returns 10 fields and allows pageSize up to 200. - `bpmMin` integer: Give together with bpmMax. - `bpmMax` integer - `durationMin` integer: Seconds. Give together with durationMax. - `durationMax` integer - `libraryType` string: e.g. "production" | "trailer" | "promotion". - `partition` 'independent' | 'universal': Site partition: "independent" (独立精选) or "universal" (环球UPM). Omit to search both. - `withFacets` boolean: Also return facet counts for the current result set (slower). Default false. - `includeLabels` string[]: includeLabels: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeLabels` string[]: excludeLabels: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeAlbums` string[]: includeAlbums: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeAlbums` string[]: excludeAlbums: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeInstrumentation` string[]: includeInstrumentation: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeInstrumentation` string[]: excludeInstrumentation: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeTempo` string[]: includeTempo: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeTempo` string[]: excludeTempo: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeGenre` string[]: includeGenre: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeGenre` string[]: excludeGenre: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeMood` string[]: includeMood: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeMood` string[]: excludeMood: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `includeMusicFor` string[]: includeMusicFor: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). - `excludeMusicFor` string[]: excludeMusicFor: facet values copied verbatim from km_vocabulary ("Parent" or "Parent;Leaf"). ## 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)