词灵 AI · API 文档

输入一句歌词、一种心情或一个场景,返回推荐歌曲。接口只返回歌曲信息、标签和高亮提示,不返回完整歌词。

所有接口均为 HTTP JSON。把下面的路径拼到 … 后面即可(实际接口地址见 config.js)。

快速开始

目前为演示环境,无需额外认证头。下面示例可直接在命令行或任意 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
randomize0 或 1,1 表示随机返回
language语言过滤,如 中文 / 英文
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs?limit=10&randomize=1"
GET/api/proxy/song/singers/az

按歌手拼音首字母分组浏览曲库歌手,# 表示数字/符号开头。

参数说明
letterA-Z 或 #,默认 A
limit返回数量上限,默认 200
offset分页偏移,默认 0
curl 示例
curl "{{API_BASE}}/api/proxy/song/singers/az?letter=A"
GET/api/proxy/song/songs/titles/az

按歌名拼音首字母分组浏览曲库歌曲,# 表示数字/符号开头。

参数说明
letterA-Z 或 #,默认 A
limit返回数量上限,默认 200
offset分页偏移,默认 0
curl 示例
curl "{{API_BASE}}/api/proxy/song/songs/titles/az?letter=A"
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}'