Ciling AI · API Docs

Send a lyric line, a mood or an occasion, and get recommended songs back. The API returns song info, tags and highlight hints only — never full lyrics.

All endpoints speak HTTP JSON. Append the paths below to … (the actual API address lives in config.js).

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.

GET/health

Health check, used to confirm the service is online.

curl {{API_BASE}}/health

Chat recommendation

POST/api/chat

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.

Request body
{
  "text": "Walking alone on a rainy street, feeling a bit down",
  "user_id": "client-demo",
  "session_id": null
}
FieldRequiredDescription
textYesThe user's input sentence
user_idNoCaller identifier
session_idNoSession ID; null on the first call
curl example
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/....

GET/api/proxy/song/songs

Paginated song list; filter by language or return randomized results.

ParameterDescription
limitPage size, 1-100, default 20
offsetOffset, default 0
randomize0 or 1; 1 means randomized
languageLanguage filter, e.g. Chinese / English
curl example
curl "{{API_BASE}}/api/proxy/song/songs?limit=10&randomize=1"
GET/api/proxy/song/singers/az

Browse library singers grouped by pinyin initial; # means digits/symbols.

ParameterDescription
letterA-Z or #, default A
limitMax results, default 200
offsetPagination offset, default 0
curl example
curl "{{API_BASE}}/api/proxy/song/singers/az?letter=A"
GET/api/proxy/song/songs/titles/az

Browse library songs grouped by title pinyin initial; # means digits/symbols.

ParameterDescription
letterA-Z or #, default A
limitMax results, default 200
offsetPagination offset, default 0
curl example
curl "{{API_BASE}}/api/proxy/song/songs/titles/az?letter=A"
GET/api/proxy/song/songs/query

Unified lyric/song search without an LLM: exact match on title/artist/lyrics first, with automatic vector-semantic fallback when nothing hits.

ParameterDescription
qRequired; title / artist / lyric / natural-language description
limitNumber of results, 1-100, default 20
min_scoreMinimum similarity for the semantic fallback, default 0.35
languageFilter by language
moodFilter by mood tag
sceneFilter by scene tag
curl example
curl "{{API_BASE}}/api/proxy/song/songs/query?q=美酒加咖啡&limit=10"
GET/api/proxy/song/songs/by_mood

Exact search by mood tag, e.g. "nostalgic" or "warm".

curl example
curl "{{API_BASE}}/api/proxy/song/songs/by_mood?mood=怀旧&limit=5"
GET/api/proxy/song/songs/by_scene

Exact search by scene tag, e.g. "bedtime" or "rainy-day vibes".

curl example
curl "{{API_BASE}}/api/proxy/song/songs/by_scene?scene=睡前&limit=5"
GET/api/proxy/song/songs/semantic

Semantic vector search. Converts natural language into a vector and returns the semantically closest songs.

ParameterDescription
qRequired; a natural-language description
limitNumber of results, default 10
min_scoreMinimum similarity, default 0.2
languageFilter by language
curl example
curl "{{API_BASE}}/api/proxy/song/songs/semantic?q=quiet songs for a rainy day alone&limit=5"
GET/api/proxy/song/songs/by_id/{id}

Query song details by ID.

curl example
curl "{{API_BASE}}/api/proxy/song/songs/by_id/196665"
GET/api/proxy/song/songs/distinct_tags

Returns the mood, scene and language tags that actually exist in the library — useful for front-end display or constraining search terms.

curl example
curl "{{API_BASE}}/api/proxy/song/songs/distinct_tags"
POST/api/proxy/song/songs/{id}/weight

Manually set a song's weight; higher weight sorts first.

Request body
{"weight": 10.5}
curl example
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

Simulate a click; increases the weight by the given delta, default +0.1.

curl example
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/....

POST/api/proxy/adapter/api/parse_text

Parse natural language, extract mood, scene and tags, and normalize them to the whitelist.

Request body
{"text":"Walking alone on a rainy street, feeling a bit down"}
curl example
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"}'
POST/api/proxy/adapter/api/normalize_tag

Normalize existing tags without calling an LLM.

Request body
{"raw_emotion":"sad","raw_scene":"rainy night street","raw_tags":[]}
curl example
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"]}'
POST/api/proxy/adapter/api/recommend

End-to-end recommendation: parses tags first, then queries songs. mode is either semantic or explicit.

Request body
{"text":"songs for listening alone at night","mode":"semantic","limit":10}
curl example
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}'