---
title: "曲目剪辑版本 / Cutdown versions of a track"
method: POST
path: "/agent/v1/km_track_versions"
---

# 曲目剪辑版本 / Cutdown versions of a track

`POST /agent/v1/km_track_versions`

## Request

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

列出同一首曲子的全部剪辑版本（Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec 等）。
Lists every cutdown version of one track (Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec …).

⚠️ km_search 只索引主曲（Solr 里 track_is_main=Y），**剪辑版拿不到**，只能靠本工具取。
km_search only indexes main tracks; the shorter cutdowns are invisible to it and can ONLY be fetched here.

何时用 / When: 广告、TVC、预告片这类有硬性时长的项目，交付候选之前对每首都查一次——
有现成的 60s/30s/15s 版本，客户就不必自己剪；没有就要在交付说明里讲清楚需要自行剪辑。

入参 / Args: albumCode = 曲目的 album_code；trackNumber = **主曲**的 track_number（都取自 km_search 返回的曲目对象）。
libraryType 可选：原样透传 km_search 里那首曲子的 library_type，用来判定 web_url 的 essential / premium 段（本端点自身不返回该字段）。

返回 / Returns: { albumCode, trackNumber, total, versions[] }，versions 按时长从长到短排，字段与 km_search 的曲目对象同构。
看 track_version（版本名）、track_duration（秒）、orginal_time（mm:ss）、track_mixout（如 Backing Vocals Only，即去人声版）。
注意：剪辑版只有版本名 / 时长 / mixout / 英文描述，track_bpm 与四维标签（mood/genre/instrumentation/tempo）只有主曲那行有——它们本来就是同一首曲子，按主曲的值理解即可。
专辑号或曲目号不存在时返回空 versions[]，不报错。

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

## Request body

- object
  - `albumCode` string, required: Album code as returned by km_search (field "album_code"), e.g. "NYB17".
  - `trackNumber` union, required: track_number of the MAIN track, as returned by km_search.
    - string
    - number
  - `libraryType` string: Pass through library_type from the km_search result so web_url gets the right tier.

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