快速开始
目前为演示环境,无需额外认证头。下面示例可直接在命令行或任意 HTTP 客户端中调用。
GET/health
健康检查,用于确认服务在线。
curl {{API_BASE}}/health
聊天推荐
POST/api/chat
多轮聊天入口。发送一句歌词、心情或场景描述,返回 AI 回复和推荐歌曲列表。首次调用 session_id 传 null。
请求体
{
"text": "下雨天一个人走在街上,有点难过",
"user_id": "client-demo",
"session_id": null
}
| 字段 | 必填 | 说明 |
|---|---|---|
| text | 是 | 用户输入的一句话 |
| user_id | 否 | 调用方标识 |
| session_id | 否 | 会话 ID;首次传 null |
curl 示例
curl -X POST "{{API_BASE}}/api/chat" \
-H "Content-Type: application/json" \
-d '{"text":"想听一首失恋后一个人听的歌","user_id":"client-demo","session_id":null}'
歌曲检索
以下接口通过 /api/proxy/song/... 转发到歌曲服务。
GET/api/proxy/song/songs
分页获取歌曲列表,可按语言过滤,也可随机返回。
| 参数 | 说明 |
|---|---|
| limit | 每页数量,1-100,默认 20 |
| offset | 偏移量,默认 0 |
| randomize | 0 或 1,1 表示随机返回 |
| language | 语言过滤,如 中文 / 英文 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs?limit=10&randomize=1"
GET/api/proxy/song/singers/az
按歌手拼音首字母分组浏览曲库歌手,# 表示数字/符号开头。
| 参数 | 说明 |
|---|---|
| letter | A-Z 或 #,默认 A |
| limit | 返回数量上限,默认 200 |
| offset | 分页偏移,默认 0 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/singers/az?letter=A"
GET/api/proxy/song/songs/titles/az
按歌名拼音首字母分组浏览曲库歌曲,# 表示数字/符号开头。
| 参数 | 说明 |
|---|---|
| letter | A-Z 或 #,默认 A |
| limit | 返回数量上限,默认 200 |
| offset | 分页偏移,默认 0 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/titles/az?letter=A"
GET/api/proxy/song/songs/search
按关键词在歌名、歌手、歌词中做模糊检索。
| 参数 | 说明 |
|---|---|
| q | 必填,检索关键词 |
| title | 按歌名硬过滤,如 晴天 |
| artist | 按歌手硬过滤,如 周杰伦 |
| language | 按语言过滤 |
| mood | 按情绪标签过滤 |
| scene | 按场景标签过滤 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/search?q=晴天&limit=10"
GET/api/proxy/song/songs/query
统一歌词/歌曲检索,不经过大模型:先按歌名/歌手/歌词精确匹配,未命中再自动做向量语义兜底。
| 参数 | 说明 |
|---|---|
| q | 必填,歌名 / 歌手 / 歌词 / 自然语言描述 |
| limit | 返回条数,1-100,默认 20 |
| min_score | 语义兜底时的最小相似度,默认 0.35 |
| language | 按语言过滤 |
| mood | 按情绪标签过滤 |
| scene | 按场景标签过滤 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/query?q=美酒加咖啡&limit=10"
GET/api/proxy/song/songs/by_mood
按情绪标签精确检索,例如「怀旧」「温暖」。
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/by_mood?mood=怀旧&limit=5"
GET/api/proxy/song/songs/by_scene
按场景标签精确检索,例如「睡前」「雨天氛围」。
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/by_scene?scene=睡前&limit=5"
GET/api/proxy/song/songs/semantic
语义向量检索。把自然语言转成向量,返回语义最相近的歌曲。
| 参数 | 说明 |
|---|---|
| q | 必填,自然语言描述 |
| limit | 返回条数,默认 10 |
| min_score | 最小相似度,默认 0.2 |
| language | 按语言过滤 |
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/semantic?q=适合下雨天一个人安静听的歌&limit=5"
GET/api/proxy/song/songs/by_id/{id}
按歌曲 ID 查询详情。
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/by_id/196665"
GET/api/proxy/song/songs/distinct_tags
返回库中实际存在的情绪、场景和语言标签,可用于前端展示或约束检索词。
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/distinct_tags"
POST/api/proxy/song/songs/{id}/weight
手动设置歌曲权重,权重越高排序越靠前。
请求体
{"weight": 10.5}
curl 示例
curl -X POST "{{API_BASE}}/api/proxy/song/songs/196665/weight" \
-H "Content-Type: application/json" \
-d '{"weight":10.5}'
POST/api/proxy/song/songs/{id}/click
模拟一次点开,权重增加指定增量,默认 +0.1。
curl 示例
curl -X POST "{{API_BASE}}/api/proxy/song/songs/196665/click" \
-H "Content-Type: application/json" \
-d '{"delta":0.5}'
标签适配
以下接口通过 /api/proxy/adapter/api/... 转发到标签适配服务。
POST/api/proxy/adapter/api/parse_text
解析自然语言,提取情绪、场景和标签,并归一为白名单标签。
请求体
{"text":"下雨天一个人走在街上,有点难过"}
curl 示例
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/parse_text" \
-H "Content-Type: application/json" \
-d '{"text":"下雨天一个人走在街上,有点难过"}'
POST/api/proxy/adapter/api/normalize_tag
把已有标签归一化,不调用大模型。
请求体
{"raw_emotion":"难过","raw_scene":"雨夜街道","raw_tags":[]}
curl 示例
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/normalize_tag" \
-H "Content-Type: application/json" \
-d '{"raw_emotion":"难过","raw_scene":"雨夜街道","raw_tags":["开心"]}'
POST/api/proxy/adapter/api/recommend
端到端推荐:先解析标签,再查歌曲。mode 可选 semantic 或 explicit。
请求体
{"text":"适合晚上一个人听的歌","mode":"semantic","limit":10}
curl 示例
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/recommend" \
-H "Content-Type: application/json" \
-d '{"text":"适合晚上一个人听的歌","mode":"semantic","limit":5}'