搜尋:多維交集

聲調 × 押韻 × 語義同時約束

01為何要交集

GET/api/lexicon/search

/search 的每個參數都是一個維度,同時傳入即為交集。這正是填詞的實際需要:一個位置往往同時被旋律、韻腳與語義三方面約束。

押「心」韻 × 悲傷 × 兩字 × 首字高平次字高平

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?code=33&rhyme_char=心&emotion=悲傷&length=2&limit=10"

↳total 28 · 傷心 / 傷感 / 坎坎 / 堵心 / 失枕

把 code 拿掉,同樣條件是 82 個;加上聲調約束後收窄到 28 個, 而且全部都是唱得上去的選擇。

020243 協音碼

粵語九聲在旋律上實際只分四個音高層。0243 制把每個字映射成一位數字, 數字本身就是由低至高的次序 —— 這也是「0243」這個名字的由來:

碼	涵蓋聲調	音高層	例
0	4	最低	零 ling4
2	6	低	夜 je6
4	3 · 5	中	世 sai3
3	1 · 2	最高	心 sam1

一個詞的碼即逐字串接:傷心 = 33、凋零 = 30。查詢時傳 code 即可限定聲調輪廓。

碼是按聲調類比對,不是字串相等

查詢碼的每一位涵蓋該層的全部聲調 —— 例如 3 同時涵蓋聲調 1 與 2。因此 code=33 會取回所有「兩字皆屬最高層」的詞,不論是 1+1、1+2 還是 2+2。

三字、碼 342

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?code=342&limit=10"

↳total 860 · 一下下 jat1 haa5 haa6

若你手上只有旋律的相對走向而非絕對音高,改用 relative_path:+ 升、- 降、= 平,長度為字數減一。

三字、先升後降

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?relative_path=%2B-&length=3&limit=6"

↳total 432 · 丈母娘 / 上一代 / 上一個

+ 在網址中要編碼為 %2B,否則會被解讀成空格。

03押韻

傳 rhyme_char(押韻參考字)即可限定韻母 —— 毋須自己查韻表。loose_rhyme=true 會放寬到通韻組,可用選擇大幅增加。

與「夜」通韻的兩字詞

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?rhyme_char=夜&loose_rhyme=true&length=2&limit=10"

↳total 1,270（嚴韻同條件約十分之一）

回應中的 rhyme 欄位是該詞最後一個字的韻母,可用於自行分組。

04語義維度

參數	型別	預設	說明
`emotion`	string	—	情緒。十個值:中性、喜悅、厭惡、平靜、悲傷、憤怒、恐懼、激昂、驚訝、愛慕。
`theme`	string	—	主題意象,例如思念 / 愛情 / 孤獨 / 漂泊。與情緒是不同維度。
`valence`	string	—	情感極性:正 / 負 / 中。
`category`	string	—	語義分類(WordNet lexname),例如 noun.plant。共 48 個。
`reg`	string	—	語域:粵(口語) / 通(通用) / 雅(書面)。
`pos`	string	—	詞性:n / v / a / r。
`is_canto`	boolean	—	僅限粵語特有詞。

情緒 ≠ 主題

「思念」是主題不是情緒。傳成 emotion=思念 會回 422 並提示改用theme。全部合法值可由 /api/lexicon/vocabulary 一次取得。

思念 × 書面語 × 兩字

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?theme=思念&reg=雅&length=2&limit=10"

↳total 62 · 久別 / 惦念 / 眷念

theme_scope 控制主題的取值範圍:

值	意義	「孤獨 × 兩字」實測
`tagged`	僅用原始標註（預設，精確）	546
`all`	併入語義群傳播推測（範圍較廣）	1,565
`inferred`	僅取推測結果	—

傳播推測是把主題沿語義關係擴散到未標註的詞;範圍大得多,但約三成不準確。需要準度就維持預設,需要廣度(例如給人挑選的候選池)才改 all。詳見資料品質申報。

05排序控制

參數	型別	預設	說明
`near_jyutping`	string	—	音近排序:依聲母與韻母與指定粵拼的接近程度排序。用於「差一點就啱音」的替代字。
`near`	string	—	含指定字元的詞條優先。
`similarity_search`	boolean	—	依聲調近似度排序(而非嚴格相等)。
`quality`	boolean	—	僅返回具釋義的詞條,常用者優先。給人看的候選建議開啟。
`only_entry`	boolean	—	僅返回詞典正式詞條。
`exclude_entry`	boolean	—	排除詞典正式詞條。

與 sam1 音近的兩字詞

cURL

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/search?near_jyutping=sam1&length=2&limit=10"

↳total 108,482（排序而非過濾 —— 前列才是音最近的）

near_jyutping 與 near 是排序參數,不會縮小結果集。要縮小請配合 code / rhyme_char 使用。

06完整參數

上列之外還有 scheme(協音制,預設 0243)與 tone_sandhi(是否計入變調)。完整清單與型別見 API 參考。

07分頁

limit 與 offset。total 是符合條件的真實總數,可據此算頁數。

每頁上限:Free 50、Indie 100、Studio / Label 200。
offset 上限:Free 480(約十頁),付費層不限。
結果排序在同一查詢條件下穩定,翻頁不會重複或漏掉詞條。

注意分頁不會省配額 —— 配額計的是取回的不重複詞條數, 翻十頁就是取了十頁的詞。