---
title: "相似曲目 / Find tracks similar to a track"
method: POST
path: "/agent/v1/km_similar_by_track"
---

# 相似曲目 / Find tracks similar to a track

`POST /agent/v1/km_similar_by_track`

## Request

- Base URL: `https://share.kindlemusic.cn`
- URL: `https://share.kindlemusic.cn/agent/v1/km_similar_by_track`
- 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`)

以曲库里一首已有曲目为锚点，找音频听感相似的曲目（向量检索，不是关键词）。
Audio-similarity search anchored on an existing catalog track (vector search, not keywords).

何时用 / When: 用户说"再来一些像这首的"，或你已经命中一首合适的曲目、想扩出一组候选时。
接力用法：对"七八分像"的曲目取相似 → 挑出更像的一首再取相似，两三轮通常就能逼近目标。

入参 / Args: id = km_search 返回的曲目 id（不是 track_identity），须是主版本。limit 默认 12，上限 50。
不认 partition（独立精选 / 环球UPM 分区）；要按 BPM / 时长 / 标签收窄，拿结果在本地筛。
返回 / Returns: { searchId, total, tracks[] }，曲目字段与 km_search 一致。

返回的 track_url 仅供试听/临时分析，见 audioNotice。
Returned track_url values are for audition / temporary analysis only; see audioNotice.

## Request body

- object
  - `id` union, required: Track id as returned by km_search (field "id").
    - string
    - number
  - `limit` integer: Default 12, clamped to 50.
  - `libraryType` string

## 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)