API 參考

全部端點、參數與回應

01關於本頁

本頁由 OpenAPI 規格在建置時生成,與伺服器端保持一致 —— 參數、預設值與說明皆直接取自規格,不會與實作脫節。

Cantonese Prosody & Semantics API v1.0.0
https://api.writer.hk
想即場試呼叫?
/api/lexicon/docs 提供互動式探索器(Swagger UI),可直接在瀏覽器發出請求。 本頁則是給你在寫程式時對照用的靜態參考 —— 兩者定位不同。

02檢索與工作流

全部端點皆需 Authorization: Bearer 密鑰;未帶密鑰亦可呼叫, 惟以匿名身分計額(見錯誤處理)。

GET/api/lexicon/search
searchWordsSearch

主檢索:絕對協音碼/相對音高/押韻,交叉情感、語域、詞性、字數等維度。

查詢/路徑參數
參數型別預設說明
codestring絕對協音碼,例如 342;留空則僅依其他維度篩選。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。
rhyme_charstring押韻參考字
schemestring0243
tone_sandhibooleanfalse
loose_rhymebooleanfalse
exclude_entrybooleanfalse
only_entrybooleanfalse
regstring語域:粵|通|雅
posstringn|v|a|r
emotionstring情緒標籤,例如 悲傷|喜悅|激昂(參見 /vocabulary)
valencestring正|負|中
themestring主題意象,例如 思念|愛情|孤獨|漂泊
theme_scopestringtaggedtagged:僅用原始標註(預設,精確) | all:併入語義群傳播推測(範圍較廣,約三成不準確) | inferred:僅取推測結果
categorystring語義分類 lexname,例如 noun.plant(參見 /categories)
is_cantoboolean僅限粵語特有詞
lengthinteger字數
relative_pathstring相對音高路徑,例如 + - =
similarity_searchbooleanfalse依聲調近似度排序
qualitybooleanfalse僅返回具釋義之詞條,常用者優先
nearstring含指定字元之詞條優先排序
near_jyutpingstring音近排序:依聲母與韻母與指定粵拼之接近程度排序
limitinteger50
offsetinteger0
GET/api/lexicon/browse
browseFacetsBrowse

即時維度瀏覽 —— 例如「押 oi 韻 × 悲傷 × 雅語」。 排序穩定並支援 offset 分頁。`code` 使用預先計算之集合,僅支援 0243 制且不含變調; 如需變調或其他協音制,請改用 /search。

查詢/路徑參數
參數型別預設說明
rhymestring
emotionstring
valencestring
regstring
posstring
lengthinteger
themestring
theme_scopestringtaggedtagged:僅用原始標註(預設) | all:併入語義群傳播推測
categorystring
codestring協音碼,例如 342(0243 制,不含變調)
limitinteger50
offsetinteger0
GET/api/lexicon/synonyms
getSynonyms同義詞檢索(可疊加聲韻條件)

由 836,004 條語義關係中檢索同義詞,並可同時約束協音碼、押韻、字數、語域與詞性。此為「換字」之核心端點:例如`?word=高興&code=34&length=2` 即「與『高興』同義、協音碼 34 之雙字詞」,可直接用於修正倒字而不損原意。

查詢/路徑參數
參數型別預設說明
word必填string來源詞
codestring限定協音碼,例如 342 —— 換字修正倒字之用。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。
rhyme_charstring限定與此字押韻
lengthinteger限定字數
regstring語域:粵|通|雅
posstring詞性:n|v|a|r
sourcestringall關係來源:all(預設) | curated(WordNet 人工基底) | generated(模型生成)
schemestring0243
tone_sandhibooleanfalse
loose_rhymebooleanfalse寬韻(通韻組)
limitinteger50
offsetinteger0
GET/api/lexicon/antonyms
getAntonyms反義詞檢索(可疊加聲韻條件)

由 836,004 條語義關係中檢索反義詞,參數與 /synonyms 相同。常用於副歌對比:例如 `?word=光明&rhyme_char=心` 即「與『光明』相反、且與『心』押韻」,可得黑暗、陰暗等。

查詢/路徑參數
參數型別預設說明
word必填string來源詞
codestring限定協音碼,例如 342 —— 換字修正倒字之用。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。
rhyme_charstring限定與此字押韻
lengthinteger限定字數
regstring語域:粵|通|雅
posstring詞性:n|v|a|r
sourcestringall關係來源:all(預設) | curated(WordNet 人工基底) | generated(模型生成)
schemestring0243
tone_sandhibooleanfalse
loose_rhymebooleanfalse寬韻(通韻組)
limitinteger50
offsetinteger0
GET/api/lexicon/categories
listCategoriesCategories

語義分類目錄(WordNet lexname)及各分類詞條數。 此為全庫覆蓋率最高之語義維度(語義群 100% 具分類,可推及 137,978 個詞條)。 本端點僅返回目錄、不含詞條,故不計入每日不重複詞條配額。

無參數。

GET/api/lexicon/category/{name}/words
categoryWordsCategory Words

分類檢索:指定語義分類,並可疊加全套音韻、情感與語域條件。 例:`/category/noun.plant/words?rhyme_char=愛&reg=雅&length=2` 即「植物類、押『愛』韻、雅語、雙字詞」。

查詢/路徑參數
參數型別預設說明
name必填string
rhyme_charstring押韻參考字
codestring絕對協音碼,例如 342
regstring
posstring
emotionstring
valencestring
themestring
lengthinteger
qualitybooleanfalse僅返回具釋義之詞條
limitinteger50
offsetinteger0
GET/api/lexicon/autocomplete
autocompleteAutocomplete

前綴自動完成。 ⚠️ 對 **API key** 計入每日配額。逐個前綴掃就可以把詞表倒出,唔計數嘅話 呢度就係枚舉詞庫**最平**嘅路徑 —— 等於喺配額牆上開個窿。 網站會員同匿名維持免費:打字提示係介面基本互動,計數會令輸入框變成計價器。

查詢/路徑參數
參數型別預設說明
prefix必填string
limitinteger20
GET/api/lexicon/word/{text}
getWordCardWord

完整詞條資料:讀音、多重詞義、同義/反義、情感標註與量詞搭配。 註:本服務不提供 `min_score` 參數。基礎資料中的 score 為來源常數標籤 (模型生成恆為 0.9、人工基底為 0.6/0.5),若作為信心值使用,「提高嚴格度」 反而會篩去人工基底而僅保留模型生成結果,語義與預期相反。 請改用 `source` 參數區分來源。

查詢/路徑參數
參數型別預設說明
text必填string
relations_limitinteger150每種關係(同義/反義)最多返回多少條。**降低此值可直接節省每日詞條配額** —— 配額按實際返回的詞計算,介面只需顯示十數條時,毋須取滿 150 條。
sourcestringall同/反義來源:all|curated(WordNet 人工基底)|generated(模型補完)
POST/api/lexicon/annotate
annotateTextAnnotate

逐字標註:為輸入文本標示粵拼、協音碼、韻母與多音字(僅受速率限制,不計配額)。

請求主體(AnnotateBody)
參數型別預設說明
text必填string
schemestring0243
GET/api/lexicon/homophones/{char}
getHomophonesHomophones

同音字:依讀音分組,列出粵拼相同之單字。

查詢/路徑參數
參數型別預設說明
char必填string
GET/api/lexicon/vocabulary
getVocabularyVocabulary

合法 emotion / theme / valence 值 + 各自詞數。客戶靠估邊個值合法 = 一定出事, 所以直接由 DB 實時列出(換詞典版本自動跟住變)。

無參數。

GET/api/lexicon/usage
getUsageUsage

用量查詢:本日與本月請求數、計費點數、各端點分佈,以及本日已取不重複詞條數與配額。

無參數。

POST/api/lexicon/workflow/fix-contour
fixContourWf Fix Contour

倒字修正:偵測拗音位置,並就每處提供整詞或單字替換候選。 候選必定同時符合前後兩側之音高走向 —— 若僅符合單側,修正前段將於後段產生新的拗音。 當兩側條件無法同時滿足(受音域上下限所限)時,回應之 `fixable` 為 false 並附原因。

請求主體(FixContourBody)
參數型別預設說明
line必填string單行歌詞
melodynumber[]每個漢字對應一個 MIDI 音高;null 表示該處不限
movesstring相鄰字音高走向序列,例如 "+-="(長度為字數減一)
schemestring0243
max_candidatesinteger8
GET/api/lexicon/workflow/rhyme-close
rhymeCloseWf Rhyme Close

韻腳收句:依**末字聲調**分組之韻腳詞。末音既定時,選取音層相符之組別即可套用。

查詢/路徑參數
參數型別預設說明
rhyme_charstring押韻參考字
rhymestring韻母,例如 oi
emotionstring
themestring
valencestring
regstring
posstring
lengthinteger
loosebooleanfalse寬韻(通韻組)
limitinteger40
GET/api/lexicon/attribution
getAttributionAttribution

本服務所提供資料之來源與標示義務(機器可讀格式)。 CC BY 系授權之標示義務**將隨資料傳遞至下游**:貴方若將本服務之釋義、例詞、量詞或 語義關係嵌入自身產品,該產品亦須標示原始來源。`required_notice` 為可直接引用之 標示文字,適用於產品「關於」頁或說明文件。

無參數。

GET/api/lexicon/version
getVersionVersion

目前生效之詞庫資料版本。

無參數。

03規格下載

完整 OpenAPI 3.1 規格(含全部回應 schema)可直接取得,用於產生任何語言的用戶端:

curl -o openapi.json https://api.writer.hk/api/lexicon/openapi.json

官方 TypeScript 與 Python 用戶端亦由同一份規格生成,見SDK