API 參考
全部端點、參數與回應
01關於本頁
本頁由 OpenAPI 規格在建置時生成,與伺服器端保持一致 —— 參數、預設值與說明皆直接取自規格,不會與實作脫節。
https://api.writer.hk
/api/lexicon/docs 提供互動式探索器(Swagger UI),可直接在瀏覽器發出請求。 本頁則是給你在寫程式時對照用的靜態參考 —— 兩者定位不同。02檢索與工作流
全部端點皆需 Authorization: Bearer 密鑰;未帶密鑰亦可呼叫, 惟以匿名身分計額(見錯誤處理)。
/api/lexicon/searchsearchWordsSearch主檢索:絕對協音碼/相對音高/押韻,交叉情感、語域、詞性、字數等維度。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
code | string | — | 絕對協音碼,例如 342;留空則僅依其他維度篩選。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。 |
rhyme_char | string | — | 押韻參考字 |
scheme | string | 0243 | — |
tone_sandhi | boolean | false | — |
loose_rhyme | boolean | false | — |
exclude_entry | boolean | false | — |
only_entry | boolean | false | — |
reg | string | — | 語域:粵|通|雅 |
pos | string | — | n|v|a|r |
emotion | string | — | 情緒標籤,例如 悲傷|喜悅|激昂(參見 /vocabulary) |
valence | string | — | 正|負|中 |
theme | string | — | 主題意象,例如 思念|愛情|孤獨|漂泊 |
theme_scope | string | tagged | tagged:僅用原始標註(預設,精確) | all:併入語義群傳播推測(範圍較廣,約三成不準確) | inferred:僅取推測結果 |
category | string | — | 語義分類 lexname,例如 noun.plant(參見 /categories) |
is_canto | boolean | — | 僅限粵語特有詞 |
length | integer | — | 字數 |
relative_path | string | — | 相對音高路徑,例如 + - = |
similarity_search | boolean | false | 依聲調近似度排序 |
quality | boolean | false | 僅返回具釋義之詞條,常用者優先 |
near | string | — | 含指定字元之詞條優先排序 |
near_jyutping | string | — | 音近排序:依聲母與韻母與指定粵拼之接近程度排序 |
limit | integer | 50 | — |
offset | integer | 0 | — |
/api/lexicon/browsebrowseFacetsBrowse即時維度瀏覽 —— 例如「押 oi 韻 × 悲傷 × 雅語」。 排序穩定並支援 offset 分頁。`code` 使用預先計算之集合,僅支援 0243 制且不含變調; 如需變調或其他協音制,請改用 /search。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
rhyme | string | — | — |
emotion | string | — | — |
valence | string | — | — |
reg | string | — | — |
pos | string | — | — |
length | integer | — | — |
theme | string | — | — |
theme_scope | string | tagged | tagged:僅用原始標註(預設) | all:併入語義群傳播推測 |
category | string | — | — |
code | string | — | 協音碼,例如 342(0243 制,不含變調) |
limit | integer | 50 | — |
offset | integer | 0 | — |
/api/lexicon/synonymsgetSynonyms同義詞檢索(可疊加聲韻條件)由 836,004 條語義關係中檢索同義詞,並可同時約束協音碼、押韻、字數、語域與詞性。此為「換字」之核心端點:例如`?word=高興&code=34&length=2` 即「與『高興』同義、協音碼 34 之雙字詞」,可直接用於修正倒字而不損原意。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
word必填 | string | — | 來源詞 |
code | string | — | 限定協音碼,例如 342 —— 換字修正倒字之用。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。 |
rhyme_char | string | — | 限定與此字押韻 |
length | integer | — | 限定字數 |
reg | string | — | 語域:粵|通|雅 |
pos | string | — | 詞性:n|v|a|r |
source | string | all | 關係來源:all(預設) | curated(WordNet 人工基底) | generated(模型生成) |
scheme | string | 0243 | — |
tone_sandhi | boolean | false | — |
loose_rhyme | boolean | false | 寬韻(通韻組) |
limit | integer | 50 | — |
offset | integer | 0 | — |
/api/lexicon/antonymsgetAntonyms反義詞檢索(可疊加聲韻條件)由 836,004 條語義關係中檢索反義詞,參數與 /synonyms 相同。常用於副歌對比:例如 `?word=光明&rhyme_char=心` 即「與『光明』相反、且與『心』押韻」,可得黑暗、陰暗等。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
word必填 | string | — | 來源詞 |
code | string | — | 限定協音碼,例如 342 —— 換字修正倒字之用。協音碼依**聲調類**比對,而非字串相等:例如查詢碼 34 之首位涵蓋聲調 1 與 2,故回應中之 `code` 可能為 94 等更細緻之記法,兩者屬同一協音類。 |
rhyme_char | string | — | 限定與此字押韻 |
length | integer | — | 限定字數 |
reg | string | — | 語域:粵|通|雅 |
pos | string | — | 詞性:n|v|a|r |
source | string | all | 關係來源:all(預設) | curated(WordNet 人工基底) | generated(模型生成) |
scheme | string | 0243 | — |
tone_sandhi | boolean | false | — |
loose_rhyme | boolean | false | 寬韻(通韻組) |
limit | integer | 50 | — |
offset | integer | 0 | — |
/api/lexicon/categorieslistCategoriesCategories語義分類目錄(WordNet lexname)及各分類詞條數。 此為全庫覆蓋率最高之語義維度(語義群 100% 具分類,可推及 137,978 個詞條)。 本端點僅返回目錄、不含詞條,故不計入每日不重複詞條配額。
無參數。
/api/lexicon/category/{name}/wordscategoryWordsCategory Words分類檢索:指定語義分類,並可疊加全套音韻、情感與語域條件。 例:`/category/noun.plant/words?rhyme_char=愛®=雅&length=2` 即「植物類、押『愛』韻、雅語、雙字詞」。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
name必填 | string | — | — |
rhyme_char | string | — | 押韻參考字 |
code | string | — | 絕對協音碼,例如 342 |
reg | string | — | — |
pos | string | — | — |
emotion | string | — | — |
valence | string | — | — |
theme | string | — | — |
length | integer | — | — |
quality | boolean | false | 僅返回具釋義之詞條 |
limit | integer | 50 | — |
offset | integer | 0 | — |
/api/lexicon/autocompleteautocompleteAutocomplete前綴自動完成。 ⚠️ 對 **API key** 計入每日配額。逐個前綴掃就可以把詞表倒出,唔計數嘅話 呢度就係枚舉詞庫**最平**嘅路徑 —— 等於喺配額牆上開個窿。 網站會員同匿名維持免費:打字提示係介面基本互動,計數會令輸入框變成計價器。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
prefix必填 | string | — | — |
limit | integer | 20 | — |
/api/lexicon/word/{text}getWordCardWord完整詞條資料:讀音、多重詞義、同義/反義、情感標註與量詞搭配。 註:本服務不提供 `min_score` 參數。基礎資料中的 score 為來源常數標籤 (模型生成恆為 0.9、人工基底為 0.6/0.5),若作為信心值使用,「提高嚴格度」 反而會篩去人工基底而僅保留模型生成結果,語義與預期相反。 請改用 `source` 參數區分來源。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
text必填 | string | — | — |
relations_limit | integer | 150 | 每種關係(同義/反義)最多返回多少條。**降低此值可直接節省每日詞條配額** —— 配額按實際返回的詞計算,介面只需顯示十數條時,毋須取滿 150 條。 |
source | string | all | 同/反義來源:all|curated(WordNet 人工基底)|generated(模型補完) |
/api/lexicon/annotateannotateTextAnnotate逐字標註:為輸入文本標示粵拼、協音碼、韻母與多音字(僅受速率限制,不計配額)。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
text必填 | string | — | — |
scheme | string | 0243 | — |
/api/lexicon/homophones/{char}getHomophonesHomophones同音字:依讀音分組,列出粵拼相同之單字。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
char必填 | string | — | — |
/api/lexicon/vocabularygetVocabularyVocabulary合法 emotion / theme / valence 值 + 各自詞數。客戶靠估邊個值合法 = 一定出事, 所以直接由 DB 實時列出(換詞典版本自動跟住變)。
無參數。
/api/lexicon/usagegetUsageUsage用量查詢:本日與本月請求數、計費點數、各端點分佈,以及本日已取不重複詞條數與配額。
無參數。
/api/lexicon/workflow/fix-contourfixContourWf Fix Contour倒字修正:偵測拗音位置,並就每處提供整詞或單字替換候選。 候選必定同時符合前後兩側之音高走向 —— 若僅符合單側,修正前段將於後段產生新的拗音。 當兩側條件無法同時滿足(受音域上下限所限)時,回應之 `fixable` 為 false 並附原因。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
line必填 | string | — | 單行歌詞 |
melody | number[] | — | 每個漢字對應一個 MIDI 音高;null 表示該處不限 |
moves | string | — | 相鄰字音高走向序列,例如 "+-="(長度為字數減一) |
scheme | string | 0243 | — |
max_candidates | integer | 8 | — |
/api/lexicon/workflow/rhyme-closerhymeCloseWf Rhyme Close韻腳收句:依**末字聲調**分組之韻腳詞。末音既定時,選取音層相符之組別即可套用。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
rhyme_char | string | — | 押韻參考字 |
rhyme | string | — | 韻母,例如 oi |
emotion | string | — | — |
theme | string | — | — |
valence | string | — | — |
reg | string | — | — |
pos | string | — | — |
length | integer | — | — |
loose | boolean | false | 寬韻(通韻組) |
limit | integer | 40 | — |
/api/lexicon/attributiongetAttributionAttribution本服務所提供資料之來源與標示義務(機器可讀格式)。 CC BY 系授權之標示義務**將隨資料傳遞至下游**:貴方若將本服務之釋義、例詞、量詞或 語義關係嵌入自身產品,該產品亦須標示原始來源。`required_notice` 為可直接引用之 標示文字,適用於產品「關於」頁或說明文件。
無參數。
/api/lexicon/versiongetVersionVersion目前生效之詞庫資料版本。
無參數。
03規格下載
完整 OpenAPI 3.1 規格(含全部回應 schema)可直接取得,用於產生任何語言的用戶端:
curl -o openapi.json https://api.writer.hk/api/lexicon/openapi.json官方 TypeScript 與 Python 用戶端亦由同一份規格生成,見SDK。
