{"openapi":"3.1.0","info":{"title":"Kindle Music Agent API","version":"0.10.1","description":"Search 2M+ licensed production-music tracks, find similar ones by track or audio, share pick lists.\n\nEach MCP tool is mirrored as POST /agent/v1/{tool}; request body = the tool arguments. MCP (Streamable HTTP): https://share.kindlemusic.cn/mcp/oauth (OAuth) or https://share.kindlemusic.cn/mcp (API key, optional).\nGet an API key (kmak_…) at https://www.kindlemusic.cn/essential/account/api-keys, or use OAuth 2.1 (authorization server https://share.kindlemusic.cn).\nReturned track_url / peaks_url are preview streams for audition and temporary analysis only; never store, redistribute or export them.","contact":{"url":"https://www.kindlemusic.cn/essential/developers"}},"externalDocs":{"url":"https://www.kindlemusic.cn/essential/developers"},"servers":[{"url":"https://share.kindlemusic.cn"}],"x-mcp":[{"url":"https://share.kindlemusic.cn/mcp/oauth","transport":"streamable-http","auth":"oauth2"},{"url":"https://share.kindlemusic.cn/mcp","transport":"streamable-http","auth":"bearer (optional)"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"kmak_ API key（https://www.kindlemusic.cn/essential/account/api-keys）或 OAuth access token（kmat_）"},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://share.kindlemusic.cn/oauth/authorize","tokenUrl":"https://share.kindlemusic.cn/oauth/token","refreshUrl":"https://share.kindlemusic.cn/oauth/token","scopes":{"agent:search":"需求归一化（km_normalize_brief）","agent:resultset":"生成选曲结果页（km_create_result_set）","agent:audio":"参考音频上传与相似检索（km_request_upload / km_similar_by_audio）"}}}}}},"paths":{"/agent/v1/km_vocabulary":{"post":{"operationId":"km_vocabulary","summary":"曲库筛选词表 / Faceted vocabulary","description":"列出曲库全部可用的筛选值（流派/情绪/乐器/速度/适用场景/厂牌）。\nLists every filterable facet value in the catalog (genre, mood, instrumentation, tempo, music-for, label).\n\n何时用 / When: 在 km_search 里使用任何 include*/exclude* 筛选之前，先用本工具确认取值。\nCall this BEFORE using any include*/exclude* filter in km_search.\n\n入参 / Args: field（可选，facet 字段名子串，如 \"genre\"/\"mood\"/\"library\"）；query（可选，对取值与中文名做不区分大小写的子串过滤，中文也能查，如 query=\"悲伤\"）。\n\n返回 / Returns: 每个 facet 字段的 { param, values }，values 里每项是 { value, labelZh, count }。param 就是 km_search 里该字段对应的入参名。\n顶层另有 labels[]：320 个厂牌的 { library_name, library_type, company, album_count, track_count }，可用来判断某个厂牌值不值得单独收窄。\n⚠️ value 必须**原样**回填到 km_search，不要翻译、改大小写或去掉 \"Parent;Leaf\" 里的分号；改动过的值一律匹配不上。labelZh 只供你把中文 brief 映射到 canonical 值，不要回填。\ncount 用来防过度收窄：候选值 count < 200 时考虑放宽或换父级（例：`sad` 有 8.6 万首，而叶子 `sad;breakup` 只有 38 首，直接用叶子会把结果掐死）。","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","description":"Substring of a facet field name, e.g. \"genre\", \"mood\", \"instrumentation\", \"library\"."},"query":{"type":"string","description":"Case-insensitive substring filter applied to the facet values and their Chinese labels."}},"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_normalize_brief":{"post":{"operationId":"km_normalize_brief","summary":"需求槽位归一化 / Normalize a music brief","description":"把结构化的选曲需求（情绪/流派/场景/乐器/BPM 区间）交给 km 归一化成一份可执行的检索方案 SearchSpec。\nTurns a structured music brief into an executable SearchSpec (search mode, keyword, facets, bpm range).\n\n何时用 / When: 用户给的是一段项目需求而不是明确关键词时，先归一化，再把结果喂给 km_search。\nUse when the user described a project rather than a concrete query; feed the result into km_search.\n\n入参 / Args: 全部字段必须是**英文**（曲库标注与向量模型都是英文）。tempoBpmMin/Max 与 durationSecMin/Max 各自成对给。\n\n硬条件（explicitInclude / explicitExclude）会被 km 收紧，与网站助手同口径：\n- explicitInclude 的 genre / mood 降为软条件（只影响排序）；instrumentation 只保留第一个，其余降为软条件。所以只放用户点名的乐器，一次一个。\n- explicitExclude 展开后总数最多 4 个 facet 值。\n- 程度否定（\"not too loud\"、\"less epic\"、「不要太吵」）不是排除：放进 soften。放进 explicitExclude 的会被 km 自动挪到 soften。\n- soften：要「少一点」的词（英文），只从软条件召回词里去掉，不做硬排除。\n\n画面侧槽位（广告 / TVC / 预告片这类有成片的项目应该填）：\n- durationSecMin/Max：成片时长（秒）。→ 原样回传成 durationMin/durationMax，可直接塞进 km_search 的同名入参。\n- referenceTrackId：客户现用曲 / 参考曲的 km 曲目 id。→ 原样回传；拿到后**先** km_similar_by_track 扩一组听感邻居，再用本 spec 的 facets/bpm/duration 收窄，比纯文字槽位重新检索准得多。\n- hasRhythmicSfx：画面是否自带节拍性音效（脚步/打字/机械声）。true → km 折出一句英文提示「避开密集打击乐」。\n- narrationDensity：旁白密度 none/light/heavy。heavy → km 折出一句「旋律稀疏、不要人声」。\nhasRhythmicSfx=false / narrationDensity=none|light 不产生提示句（它们不构成\"要避开什么\"的约束），但仍原样回传。\n\n返回 / Returns: { searchMode, keyword, keywordContext, fallbackSearchMode, facets, bpmMin, bpmMax, durationMin, durationMax, referenceTrackId, hasRhythmicSfx, narrationDensity, searchId }。\nfacets 的键就是 km_search 的 include*/exclude* 入参名，可直接透传。\nkeywordContext 为上面两个画面槽位折出的英文提示句（没填就为 null）：用 searchField=ai 时把它拼在 keyword 前面，让改写链路把\"要避开什么\"一起考虑进去。","x-required-scope":"agent:search","security":[{"agentKey":[]},{"oauth2":["agent:search"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mood":{"type":"array","items":{"type":"string"},"description":"English mood words, e.g. [\"uplifting\",\"confident\"]."},"genre":{"type":"array","items":{"type":"string"},"description":"English genre words."},"musicFor":{"type":"array","items":{"type":"string"},"description":"English usage scenarios, e.g. [\"corporate promo\"]."},"instrumentsInferred":{"type":"array","items":{"type":"string"},"description":"English instrument names inferred from the brief."},"explicitInclude":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Hard include constraints keyed by facet, e.g. {\"genre\":[\"Rock\"]}."},"explicitExclude":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Hard exclude constraints keyed by facet. Only for \"no / never X\"; degree negations belong in soften."},"soften":{"type":"array","items":{"type":"string"},"description":"English words to tone down, not exclude (e.g. \"not too sad\" → [\"sad\"]). Removed from the soft-leg recall terms only."},"tempoBpmMin":{"type":"integer"},"tempoBpmMax":{"type":"integer"},"projectContext":{"type":"string","description":"One-line English summary of the project, e.g. \"30s corporate tech promo\"."},"durationSecMin":{"type":"integer","minimum":0,"description":"Finished-cut length in seconds. Give together with durationSecMax."},"durationSecMax":{"type":"integer","minimum":0},"referenceTrackId":{"type":"string","description":"km track id of the music the client is already using / referencing."},"hasRhythmicSfx":{"type":"boolean","description":"True when the picture carries its own rhythmic sound effects (footsteps, typing, machinery)."},"narrationDensity":{"type":"string","enum":["none","light","heavy"],"description":"Voice-over density over the cut."}},"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_search":{"post":{"operationId":"km_search","summary":"曲库检索 / Search the catalog","description":"在 Kindle Music 正版曲库里检索曲目或专辑，支持关键词、facet 筛选、BPM 与时长区间。\nSearches the Kindle Music production-music catalog: keyword + facet filters + bpm/duration ranges.\n\nsearchField 怎么选 / Choosing searchField:\n- keywords：关键词匹配，默认值。多个词之间是 OR、按命中词数排序，所以加不同维度的词（用途 + 情绪 + 乐器）比堆近义词有用；英文加双引号是短语匹配（\"epic trailer\"）。不要写 AND/OR/NOT；开头的 -term 按字面匹配，不表示排除。\n  剧情词和抽象词（逆袭、对峙、回忆、高级感）曲库标签里很少出现，会把排序带偏：先翻译成情绪 / 乐器 / 速度这类音乐描述再检索。\n  expand=\"fast\"：中文按词翻译 + 同义扩展（结果稳定，同一个词每次扩成一样）；expand=\"deep\"：映射到曲库标准词，召回更窄、最慢约 1 分钟。不带 expand 时 keyword 必须是英文。\n  带 expand 时中文否定从句（不要X / 去掉X / 避免X）会从 keyword 里剥离并映射成 exclude（「不要太X」这类程度否定映射成降权），一次最多 3 条，结果见 derivedNegations。\n- ai：一句自然语言描述（可中文），后端整句理解改写后检索，结果看前排而不是总数。一两个词的需求用 keywords 更好。\n- semantic：text→audio 语义检索（英文效果最好），适合\"听感\"类描述；不可用或 0 结果时自动降级 ai。\n- track：按英文原曲名查（去掉前导序号与扩展名，中文译名搜不到）。album：按专辑编号/名查，编号不区分大小写、连字符、空格与前导零。\n- lyrics：按歌词查（可中文）。composer：按作曲者查（只能英文）。\n- 手里是下载文件名、UPM 链接、本站链接或 PUC-045 这类编号时，先用 km_resolve 定位，不要拿它当关键词。\n\n⚠️ 硬约束 / Hard constraint: searchField=keywords（未带 expand）或 composer 时 keyword 只能是英文。\nPassing Chinese with searchField=composer, or with keywords and no expand, is rejected up front (Solr matches literally → zero hits).\n\n否定 / Negation:\n- keywords：英文的 no / without X 不会被识别（反而把 X 当正向词召回），用 exclude*；中文否定需带 expand（见上）。客户的硬性排除任何模式都用 exclude* 兜底。\n- ai：直接写进句子（不要/无/别/去掉/避免 X，no/not/without X），一次最多 4 项；「不要太X」只让 X 往后排不去掉；排除后 0 结果会自动放宽。\n  响应里的 derivedNegations 说明每条否定被映射成了哪个 facet 值、是否被放宽——交付前核对它。\n\ninclude*/exclude* 的取值必须先用 km_vocabulary 取，并原样回填。同一维度多个值是 AND（includeLabels / includeAlbums 例外，是 OR）；exclude* 命中任一即排除。\n关键词不匹配厂牌名，按厂牌收窄用 includeLabels。\npartition：independent = 网站「独立精选」分区，universal = 「环球UPM」分区；不传 = 两个分区合并检索（网站精选站默认只显示独立精选）。\nbpmMin/bpmMax 与 durationMin/durationMax（秒）必须成对给出。\n\nfields 怎么选 / Choosing fields:\n- slim（默认）：每首 25 个字段（含 track_number、四维标签 + 中英文描述 + 可播放的 url），够直接做精排与交付。pageSize 上限 50。\n- compact：每首只回 10 个字段（id / album_code / track_number / track_title / track_version / track_bpm / track_duration / library_name / library_type / web_url），pageSize 上限放宽到 200。\n没有\"按 id 批量取全字段\"的端点：compact 结果需要中文描述与四维标签时，只能对收窄后的条件重跑一次 fields=slim。\n\n⚠️ BPM 半速口径 / Half-time BPM: 本曲库 55/60 与 110/120 常常是同一个脉冲的两种记法（标注方按半速还是双速记没有统一）。\n在架主曲落在 60–90 BPM 的有 12.6 万首，一刀切 bpmMin=95,bpmMax=125 会静默漏掉一大片听感完全对的曲子。\n按 BPM 收窄时要把半速区间也检索一遍再合并，否则会漏召回。\n\n返回 / Returns: { total, appliedSearchField, searchId, fields, tracks[]（字段集见 fields，含可直接打开的 web_url）, search_url（C 端复现本次检索的链接）}。\n有扩展时另带 ai_keyword / expanded（实际检索用的英文词）；有否定时带 derivedNegations。\ntranslation_failed:true 表示中文扩展失败、按空结果返回，不代表曲库里没有：换英文或改 searchField=ai 重试。\nai / lyrics / expand 受后端每日 LLM 配额；超额时返回 llmQuotaExceeded:true 且 appliedSearchField 降级为 keywords。\n\n返回的 track_url 仅供试听/临时分析，见 audioNotice。\nReturned track_url values are for audition / temporary analysis only; see audioNotice.","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"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}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_track_versions":{"post":{"operationId":"km_track_versions","summary":"曲目剪辑版本 / Cutdown versions of a track","description":"列出同一首曲子的全部剪辑版本（Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec 等）。\nLists every cutdown version of one track (Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec …).\n\n⚠️ km_search 只索引主曲（Solr 里 track_is_main=Y），**剪辑版拿不到**，只能靠本工具取。\nkm_search only indexes main tracks; the shorter cutdowns are invisible to it and can ONLY be fetched here.\n\n何时用 / When: 广告、TVC、预告片这类有硬性时长的项目，交付候选之前对每首都查一次——\n有现成的 60s/30s/15s 版本，客户就不必自己剪；没有就要在交付说明里讲清楚需要自行剪辑。\n\n入参 / Args: albumCode = 曲目的 album_code；trackNumber = **主曲**的 track_number（都取自 km_search 返回的曲目对象）。\nlibraryType 可选：原样透传 km_search 里那首曲子的 library_type，用来判定 web_url 的 essential / premium 段（本端点自身不返回该字段）。\n\n返回 / Returns: { albumCode, trackNumber, total, versions[] }，versions 按时长从长到短排，字段与 km_search 的曲目对象同构。\n看 track_version（版本名）、track_duration（秒）、orginal_time（mm:ss）、track_mixout（如 Backing Vocals Only，即去人声版）。\n注意：剪辑版只有版本名 / 时长 / mixout / 英文描述，track_bpm 与四维标签（mood/genre/instrumentation/tempo）只有主曲那行有——它们本来就是同一首曲子，按主曲的值理解即可。\n专辑号或曲目号不存在时返回空 versions[]，不报错。\n\n返回的 track_url 仅供试听/临时分析，见 audioNotice。\nReturned track_url values are for audition / temporary analysis only; see audioNotice.","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"albumCode":{"type":"string","description":"Album code as returned by km_search (field \"album_code\"), e.g. \"NYB17\"."},"trackNumber":{"type":["string","number"],"description":"track_number of the MAIN track, as returned by km_search."},"libraryType":{"type":"string","description":"Pass through library_type from the km_search result so web_url gets the right tier."}},"required":["albumCode","trackNumber"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_resolve":{"post":{"operationId":"km_resolve","summary":"链接/文件名定位 / Resolve a link, filename or album code","description":"把用户手里的下载文件名、UPM 链接、本站链接（专辑 / 厂牌 / 选曲清单 / 歌单 / 搜索结果页）、外站链接或带连字符的专辑编号，定位成下一步可用的对象。\nResolves a download filename, UPM link, kindlemusic.cn link (album / label / pick list / playlist / search page), other web link or hyphenated album code into something the other km_* tools can act on.\n\n何时用 / When: 用户贴的是 KM_PUC045_TK003_xxx.mp3、universalproductionmusic.com 链接、www.kindlemusic.cn/… 链接或 PUC-045 这类编号时，先调本工具；不要把它们当关键词丢进 km_search（会零结果）。\n\n返回 / Returns: { q, resolved }。resolved 为 null 表示认不出或库里没有。按 kind 接下一步：\n- kind=\"track\"，source 为 upm / filename（文件名 / UPM 链接）：{ albumCode, trackNumber（主曲曲号）, trackIdentity, trackTitle, albumTitle }。剪辑版文件名一律映射到主版本；接着用 km_track_versions(albumCode, trackNumber) 取全部版本，或 km_search(searchField=\"album\", keyword=albumCode) 拿曲目 id。\n- kind=\"album\"，source=\"code\"（编号）：{ albumCode, albumTitle }。接着用 km_search(searchField=\"album\", keyword=albumCode)。\n- source=\"site\"（本站链接）：\n  - kind=\"track\" 带 trackId：trackId 就是曲目 id，可直接喂 km_similar_by_track；带 trackNumber（专辑页 ?trackNumber=）：可直接喂 km_track_versions(albumCode, trackNumber)。\n  - kind=\"album\"：{ albumCode, trackId:null }，同上接 km_search(searchField=\"album\")。\n  - kind=\"label\"：{ includeLabels:[厂牌名] }，原样放进 km_search 的 includeLabels 按厂牌收窄。\n  - kind=\"resultSet\"：{ code }，选曲清单（/picks/<code>），用 km_get_result_set(code) 读回。\n  - kind=\"playlist\"：{ playlistId } 或 { shareType, shareCode }，网站歌单 / 歌单分享链接，MCP 没有读取歌单的工具，请让用户在网站打开，或说出想要的风格改用 km_search。\n  - kind=\"search\"：{ tier, args }，网站搜索结果页的条件已还原成 km_search 入参，原样传给 km_search 即可复现用户看到的那次检索。\n  - kind=\"page\"：本站首页 / 列表页 / 场景页 / 指南，没有可直接检索的对象。\n- kind=\"keywords\"，source=\"slug\"（外站链接、或本站认不出的路径）：{ keyword }，取自链接里的搜索参数或最后一段路径；可作为 km_search 的关键词（含中文时带 expand=\"fast\"，或改用 searchField=\"ai\"）。视频网站链接通常取不出曲名，有参考音频请走 km_similar_by_audio。","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"The filename, link or album code exactly as the user gave it."}},"required":["q"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_similar_by_track":{"post":{"operationId":"km_similar_by_track","summary":"相似曲目 / Find tracks similar to a track","description":"以曲库里一首已有曲目为锚点，找音频听感相似的曲目（向量检索，不是关键词）。\nAudio-similarity search anchored on an existing catalog track (vector search, not keywords).\n\n何时用 / When: 用户说\"再来一些像这首的\"，或你已经命中一首合适的曲目、想扩出一组候选时。\n接力用法：对\"七八分像\"的曲目取相似 → 挑出更像的一首再取相似，两三轮通常就能逼近目标。\n\n入参 / Args: id = km_search 返回的曲目 id（不是 track_identity），须是主版本。limit 默认 12，上限 50。\n不认 partition（独立精选 / 环球UPM 分区）；要按 BPM / 时长 / 标签收窄，拿结果在本地筛。\n返回 / Returns: { searchId, total, tracks[] }，曲目字段与 km_search 一致。\n\n返回的 track_url 仅供试听/临时分析，见 audioNotice。\nReturned track_url values are for audition / temporary analysis only; see audioNotice.","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":["string","number"],"description":"Track id as returned by km_search (field \"id\")."},"limit":{"type":"integer","minimum":1,"description":"Default 12, clamped to 50."},"libraryType":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_request_upload":{"post":{"operationId":"km_request_upload","summary":"获取参考音频上传地址 / Get a one-time upload URL","description":"签发一个一次性的参考音频上传地址，给 km_similar_by_audio 做前置。\nIssues a one-time upload URL for a reference audio file, the prerequisite of km_similar_by_audio.\n\n何时用 / When: 用户给了本地音频文件、而你手里没有 agent key（例如经 OAuth 连接器接入）时。\n有 key 的也可以用，免得在命令里写 key。\n\n用法 / Usage: 按返回的 curl 把文件以 raw body POST 到 uploadUrl（不需要 Authorization 头），\n响应里的 uploadId 传给 km_similar_by_audio。地址 30 分钟内有效，成功上传一次即作废；\nContent-Type 或空文件被拒时地址不作废，改好命令重试即可。只上传用户交给你的参考音频，不得用来转存其他文件。\n\n返回 / Returns: { uploadUrl, method, expiresAt, maxBytes, curl }。","x-required-scope":"agent:audio","security":[{"agentKey":[]},{"oauth2":["agent:audio"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_similar_by_audio":{"post":{"operationId":"km_similar_by_audio","summary":"参考音频找曲 / Find tracks similar to a reference audio","description":"用一段用户提供的参考音频找听感相似的曲库曲目。\nAudio-similarity search anchored on a reference audio clip supplied by the user.\n\n前置 / Prerequisite: 先调 km_request_upload 拿一次性上传地址，按它返回的 curl 上传文件拿到 uploadId（有效期 30 分钟）；\n手里有 agent key 时也可以直接带 Bearer POST /agent/v1/uploads。\nGet a one-time URL from km_request_upload and upload the file there (or POST /agent/v1/uploads with your key); this tool only takes the resulting uploadId.\n\n入参 / Args: uploadId 必填；start/end（秒）截取参考片段：选画面真正要用的那一段（不一定是开头），30–60 秒最合适——太短信息不够，太长会混进几种情绪；要纯音乐就避开人声段。两者要么都给要么都不给。limit 默认 20，上限 50。\n没找到相似曲目时换一个段落重试，通常能解决。\n返回 / Returns: { searchId, total, tracks[] }。\n\n返回的 track_url 仅供试听/临时分析，见 audioNotice。\nReturned track_url values are for audition / temporary analysis only; see audioNotice.","x-required-scope":"agent:audio","security":[{"agentKey":[]},{"oauth2":["agent:audio"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"uploadId":{"type":"string","description":"Id returned by the upload (km_request_upload URL or POST /agent/v1/uploads)."},"start":{"type":"number","description":"Clip start in seconds."},"end":{"type":"number","description":"Clip end in seconds."},"limit":{"type":"integer","minimum":1,"description":"Default 20, clamped to 50."},"libraryType":{"type":"string"}},"required":["uploadId"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_create_result_set":{"post":{"operationId":"km_create_result_set","summary":"生成选曲清单链接 / Publish a shareable pick list","description":"把挑好的曲目发布成一个可分享的选曲清单页面，用户打开即可试听、对比、下载小样。\nPublishes the selected tracks as a shareable pick-list page the user can open, audition and download from.\n\n何时用 / When: 完成选曲、要把结果交付给用户时（这是整个流程的交付物）。\n\n入参 / Args: sections ≤ 20，每 section tracks ≤ 50，总计 ≤ 200。中文文案一律用敬语「您」。\ncueStart/cueEnd（秒）用于标注该段落对应的画面时间码。tracks 里带上 library_type，tier 会自动判定。\n不存在或已下架的曲目会被剔除进 dropped[]，不会整单失败。\n\n返回 / Returns: { code, url, shortUrl, trackCount, dropped[] }。把 url 或 shortUrl 交给用户。","x-required-scope":"agent:resultset","security":[{"agentKey":[]},{"oauth2":["agent:resultset"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"清单标题（中文）。"},"summary":{"type":"string","description":"一段中文导语，用敬语「您」，可空。"},"tier":{"type":"string","enum":["essential","premium"],"description":"Omit to derive from the tracks' library_type."},"anchorKind":{"type":"string","enum":["none","audio","track"]},"anchorLabel":{"type":"string","description":"e.g. 参考音频《demo.wav》00:12–00:35"},"anchorTrackId":{"anyOf":[{"type":["string","number"]},{"type":"null"}]},"expiresAt":{"type":["string","null"],"description":"ISO datetime, or null for no expiry."},"searchIds":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"searchId values from the km_search / km_similar_* calls that produced these picks (attribution)."},"sections":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"note":{"type":"string"},"cueStart":{"type":"number","description":"Scene start in seconds."},"cueEnd":{"type":"number","description":"Scene end in seconds."},"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","number"],"description":"Track id from km_search."},"note":{"type":"string","description":"Why this track fits, in Chinese, addressing the user as「您」."},"library_type":{"type":"string","description":"Pass through from the search result so the tier can be derived."}},"required":["id"],"additionalProperties":false}}},"required":["title","tracks"],"additionalProperties":false},"description":"At most 20 sections, 50 tracks each, 200 tracks total."}},"required":["title","sections"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/km_get_result_set":{"post":{"operationId":"km_get_result_set","summary":"读取选曲清单 / Read back a pick list","description":"按 code 读回一份已发布的选曲清单（含分段、曲目与每首的状态）。\nReads back a published pick list by its code, including sections, tracks and each track status.\n\n何时用 / When: 用户要在既有清单上继续增删改，或要确认清单里的曲目是否仍在架。\n返回 / Returns: 清单全文；已过期或已撤销时 sections 为空数组（看 expired / revoked 字段）。\n\n返回的 track_url 仅供试听/临时分析，见 audioNotice。\nReturned track_url values are for audition / temporary analysis only; see audioNotice.","security":[{},{"agentKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"The pick-list code returned by km_create_result_set."}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"tool 结果（与 MCP tools/call 返回的 JSON 相同）","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/uploads":{"post":{"operationId":"upload_reference_audio","summary":"上传参考音频 / Upload reference audio","description":"raw body，≤20971520 字节，换 uploadId（30 分钟）给 km_similar_by_audio。没有凭据时改用 km_request_upload 签的一次性地址。","x-required-scope":"agent:audio","security":[{"agentKey":[]},{"oauth2":["agent:audio"]}],"parameters":[{"name":"X-File-Name","in":"header","required":false,"schema":{"type":"string"},"description":"原文件名，用来取扩展名"}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"audio/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"{ uploadId, expiresAt, sizeBytes, sha256 }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"入参错误或 km 业务错误：{ error, message, hint? } / { error:\"km_error\", code, message }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"需要 scope 的 tool 缺少或带了无效凭据","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/agent/v1/health":{"get":{"operationId":"health","summary":"健康检查","security":[{}],"responses":{"200":{"description":"{ ok, km, semantic }","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}