在 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.
View input schema
{
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "Query text. MUST be English for composer, and for keywords unless expand is set."
},
"searchField": {
"type": "string",
"enum": [
"keywords",
"ai",
"semantic",
"album",
"track",
"lyrics",
"composer"
],
"description": "Default \"keywords\". Use \"ai\" for natural-language / Chinese briefs."
},
"expand": {
"type": "string",
"enum": [
"fast",
"deep"
],
"description": "keywords mode only. \"fast\": translate + expand Chinese per word. \"deep\": map to canonical catalog terms (narrower, up to ~1 min)."
},
"view": {
"type": "string",
"enum": [
"tracks",
"albums"
],
"description": "Default \"tracks\"."
},
"sort": {
"type": "string",
"enum": [
"relevance",
"newest",
"oldest",
"duration"
]
},
"page": {
"type": "integer",
"minimum": 1,
"description": "1-based page number, default 1."
},
"pageSize": {
"type": "integer",
"minimum": 1,
"description": "Default 20. Clamped to 50 with fields=\"slim\", to 200 with fields=\"compact\"."
},
"fields": {
"type": "string",
"enum": [
"slim",
"compact"
],
"description": "Track field set. Default \"slim\" (25 fields). \"compact\" returns 10 fields and allows pageSize up to 200."
},
"bpmMin": {
"type": "integer",
"description": "Give together with bpmMax."
},
"bpmMax": {
"type": "integer"
},
"durationMin": {
"type": "integer",
"description": "Seconds. Give together with durationMax."
},
"durationMax": {
"type": "integer"
},
"libraryType": {
"type": "string",
"description": "e.g. \"production\" | \"trailer\" | \"promotion\"."
},
"partition": {
"type": "string",
"enum": [
"independent",
"universal"
],
"description": "Site partition: \"independent\" (独立精选) or \"universal\" (环球UPM). Omit to search both."
},
"withFacets": {
"type": "boolean",
"description": "Also return facet counts for the current result set (slower). Default false."
},
"includeLabels": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeLabels: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeLabels": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeLabels: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeAlbums": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeAlbums: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeAlbums": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeAlbums: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeInstrumentation": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeInstrumentation: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeInstrumentation": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeInstrumentation: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeTempo": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeTempo: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeTempo": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeTempo: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeGenre": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeGenre: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeGenre": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeGenre: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeMood": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeMood: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeMood": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeMood: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"includeMusicFor": {
"type": "array",
"items": {
"type": "string"
},
"description": "includeMusicFor: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
},
"excludeMusicFor": {
"type": "array",
"items": {
"type": "string"
},
"description": "excludeMusicFor: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}