---
title: "参考音频找曲 / Find tracks similar to a reference audio"
method: POST
path: "/agent/v1/km_similar_by_audio"
---

# 参考音频找曲 / Find tracks similar to a reference audio

`POST /agent/v1/km_similar_by_audio`

## Request

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

用一段用户提供的参考音频找听感相似的曲库曲目。
Audio-similarity search anchored on a reference audio clip supplied by the user.

前置 / Prerequisite: 先调 km_request_upload 拿一次性上传地址，按它返回的 curl 上传文件拿到 uploadId（有效期 30 分钟）；
手里有 agent key 时也可以直接带 Bearer POST /agent/v1/uploads。
Get 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.

入参 / Args: uploadId 必填；start/end（秒）截取参考片段：选画面真正要用的那一段（不一定是开头），30–60 秒最合适——太短信息不够，太长会混进几种情绪；要纯音乐就避开人声段。两者要么都给要么都不给。limit 默认 20，上限 50。
没找到相似曲目时换一个段落重试，通常能解决。
返回 / Returns: { searchId, total, tracks[] }。

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

## Request body

- object
  - `uploadId` string, required: Id returned by the upload (km_request_upload URL or POST /agent/v1/uploads).
  - `start` number: Clip start in seconds.
  - `end` number: Clip end in seconds.
  - `limit` integer: Default 20, 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)