快速開始

粵語歌詞創作的核心約束不是「找一個同義詞」,而是同時滿足多個互相拉扯的條件: 這個位置的聲調必須順著旋律走向、句尾必須押上指定的韻、語義必須落在某個意象範圍、 語域必須是口語還是書面。一般辭典 API 逐項都做得到,但無法在單一查詢中同時約束。

本服務將 230,317 個詞條的粵拼、0243 協音碼、韻母、語義分類、情緒、主題、語域 全部預先建成 Redis 集合索引,交集在記憶體內完成 —— 因此可以一次過問出 「押『心』韻、首字中平次字高平、屬悲傷情緒的兩字詞」。

• 登入 writer.hk 後前往組織頁。 系統會自動為你建立一個預設組織(免費方案,每日 1,500 個不重複詞條)。
• 在該組織的「密鑰」頁建立密鑰。明文密鑰僅顯示一次 —— 平台只保存其雜湊值,離開頁面後無法再取得。
• 把密鑰放進環境變數,不要寫進版本庫:

export WRITERHK_API_KEY="sk_writerhk_..."

配額與速率上限以組織為單位計算,同一組織下所有密鑰共用。 詳見組織、方案與配額。

所有端點都在 api.writer.hk 之下。密鑰以 Authorization: Bearer 標頭傳送。

curl -H "Authorization: Bearer $WRITERHK_API_KEY" \
  "https://api.writer.hk/api/lexicon/browse?category=noun.plant&emotion=悲傷&length=2&limit=12"

{
  "words": [
    {
      "char": "凋零",
      "length": 2,
      "jyutping": "diu1 ling4",
      "code": "30",
      "rhyme": "ing",
      "tones": [1, 4],
      "pos": "v",
      "reg": "雅"
    }
  ],
  "total": 25,
  "limit": 12,
  "offset": 0,
  "scheme": "0243",
  "tier": "free"
}

• code —— 0243 協音碼,每個字一位。這是本服務的核心欄位: 聲調 1/2 → 3,3/5 → 4… 詳見搜尋:多維交集。
• rhyme —— 韻母。押韻比對用這個欄位,而非最後一個字。
• total —— 符合條件的總數,不是本頁筆數。分頁靠 offset。
• tier —— 本次請求生效的方案。與你預期不符時,先看組織的訂閱狀態。

每個成功回應都帶配額標頭,讓你在撞上限之前就能自我節流:

X-Quota-Limit: 1500
X-Quota-Remaining: 1487

計費上限是每日不重複詞條數,而非請求次數 —— 重複查詢同一詞條當日不再計數。 因此實際可承載的請求量遠高於配額數字本身。額度耗盡時回應 429, 並帶 Retry-After。

• 搜尋:多維交集 —— 聲調、押韻、語義三者同時約束的完整參數。
• 語義關係:換字 —— 83.6 萬條同義／反義關係,可直接按協音碼過濾。
• 工作流端點 —— 偵測拗音並給出可換的詞。
• SDK —— TypeScript 與 Python 用戶端。