---
title: "获取参考音频上传地址 / Get a one-time upload URL"
method: POST
path: "/agent/v1/km_request_upload"
---

# 获取参考音频上传地址 / Get a one-time upload URL

`POST /agent/v1/km_request_upload`

## Request

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

签发一个一次性的参考音频上传地址，给 km_similar_by_audio 做前置。
Issues a one-time upload URL for a reference audio file, the prerequisite of km_similar_by_audio.

何时用 / When: 用户给了本地音频文件、而你手里没有 agent key（例如经 OAuth 连接器接入）时。
有 key 的也可以用，免得在命令里写 key。

用法 / Usage: 按返回的 curl 把文件以 raw body POST 到 uploadUrl（不需要 Authorization 头），
响应里的 uploadId 传给 km_similar_by_audio。地址 30 分钟内有效，成功上传一次即作废；
Content-Type 或空文件被拒时地址不作废，改好命令重试即可。只上传用户交给你的参考音频，不得用来转存其他文件。

返回 / Returns: { uploadUrl, method, expiresAt, maxBytes, curl }。

## Request body

- object

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