Quick start
This is a demo environment — no extra auth headers needed. The examples below can be called directly from the command line or any HTTP client.
Health check, used to confirm the service is online.
curl {{API_BASE}}/health
Chat recommendation
Multi-turn chat entry. Send a lyric line, a mood or a scene description; get an AI reply and a list of recommended songs. Pass session_id as null on the first call.
{
"text": "Walking alone on a rainy street, feeling a bit down",
"user_id": "client-demo",
"session_id": null
}
| Field | Required | Description |
|---|---|---|
| text | Yes | The user's input sentence |
| user_id | No | Caller identifier |
| session_id | No | Session ID; null on the first call |
curl -X POST "{{API_BASE}}/api/chat" \
-H "Content-Type: application/json" \
-d '{"text":"songs for a breakup, listening alone","user_id":"client-demo","session_id":null}'
Song search
The endpoints below are forwarded to the song service via /api/proxy/song/....
Paginated song list; filter by language or return randomized results.
| Parameter | Description |
|---|---|
| limit | Page size, 1-100, default 20 |
| offset | Offset, default 0 |
| randomize | 0 or 1; 1 means randomized |
| language | Language filter, e.g. Chinese / English |
curl "{{API_BASE}}/api/proxy/song/songs?limit=10&randomize=1"
Browse library singers grouped by pinyin initial; # means digits/symbols.
| Parameter | Description |
|---|---|
| letter | A-Z or #, default A |
| limit | Max results, default 200 |
| offset | Pagination offset, default 0 |
curl "{{API_BASE}}/api/proxy/song/singers/az?letter=A"
Browse library songs grouped by title pinyin initial; # means digits/symbols.
| Parameter | Description |
|---|---|
| letter | A-Z or #, default A |
| limit | Max results, default 200 |
| offset | Pagination offset, default 0 |
curl "{{API_BASE}}/api/proxy/song/songs/titles/az?letter=A"
Keyword fuzzy search across song title, artist and lyrics.
| Parameter | Description |
|---|---|
| q | Required; the search keyword |
| title | Hard filter by title, e.g. Sunny |
| artist | Hard filter by artist, e.g. Jay Chou |
| language | Filter by language |
| mood | Filter by mood tag |
| scene | Filter by scene tag |
curl "{{API_BASE}}/api/proxy/song/songs/search?q=Sunny&limit=10"
Unified lyric/song search without an LLM: exact match on title/artist/lyrics first, with automatic vector-semantic fallback when nothing hits.
| Parameter | Description |
|---|---|
| q | Required; title / artist / lyric / natural-language description |
| limit | Number of results, 1-100, default 20 |
| min_score | Minimum similarity for the semantic fallback, default 0.35 |
| language | Filter by language |
| mood | Filter by mood tag |
| scene | Filter by scene tag |
curl "{{API_BASE}}/api/proxy/song/songs/query?q=美酒加咖啡&limit=10"
Exact search by mood tag, e.g. "nostalgic" or "warm".
curl "{{API_BASE}}/api/proxy/song/songs/by_mood?mood=怀旧&limit=5"
Exact search by scene tag, e.g. "bedtime" or "rainy-day vibes".
curl "{{API_BASE}}/api/proxy/song/songs/by_scene?scene=睡前&limit=5"
Semantic vector search. Converts natural language into a vector and returns the semantically closest songs.
| Parameter | Description |
|---|---|
| q | Required; a natural-language description |
| limit | Number of results, default 10 |
| min_score | Minimum similarity, default 0.2 |
| language | Filter by language |
curl "{{API_BASE}}/api/proxy/song/songs/semantic?q=quiet songs for a rainy day alone&limit=5"
Query song details by ID.
curl "{{API_BASE}}/api/proxy/song/songs/by_id/196665"
Returns the mood, scene and language tags that actually exist in the library — useful for front-end display or constraining search terms.
curl "{{API_BASE}}/api/proxy/song/songs/distinct_tags"
Manually set a song's weight; higher weight sorts first.
{"weight": 10.5}
curl -X POST "{{API_BASE}}/api/proxy/song/songs/196665/weight" \
-H "Content-Type: application/json" \
-d '{"weight":10.5}'
Simulate a click; increases the weight by the given delta, default +0.1.
curl -X POST "{{API_BASE}}/api/proxy/song/songs/196665/click" \
-H "Content-Type: application/json" \
-d '{"delta":0.5}'
Tag adaptation
The endpoints below are forwarded to the tag-adaptation service via /api/proxy/adapter/api/....
Parse natural language, extract mood, scene and tags, and normalize them to the whitelist.
{"text":"Walking alone on a rainy street, feeling a bit down"}
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/parse_text" \
-H "Content-Type: application/json" \
-d '{"text":"Walking alone on a rainy street, feeling a bit down"}'
Normalize existing tags without calling an LLM.
{"raw_emotion":"sad","raw_scene":"rainy night street","raw_tags":[]}
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/normalize_tag" \
-H "Content-Type: application/json" \
-d '{"raw_emotion":"sad","raw_scene":"rainy night street","raw_tags":["happy"]}'
End-to-end recommendation: parses tags first, then queries songs. mode is either semantic or explicit.
{"text":"songs for listening alone at night","mode":"semantic","limit":10}
curl -X POST "{{API_BASE}}/api/proxy/adapter/api/recommend" \
-H "Content-Type: application/json" \
-d '{"text":"songs for listening alone at night","mode":"semantic","limit":5}'