SDK

TypeScript 與 Python

01取得

官方用戶端由 OpenAPI 規格自動生成,涵蓋全部 16 個對外 operation, 型別與伺服器端保持一致。兩者皆為單一檔案、零額外相依(Python 端只需 requests),直接複製進專案即可。

sdk/typescript/index.ts —— TypeScript(strict 模式編譯通過)
sdk/python/lexicon_client.py —— Python 3.9+
sdk/openapi.json —— OpenAPI 3.1 規格,可餵給你自己的產生器

預設就指向正式環境

兩個用戶端的預設 baseUrl 皆為 https://api.writer.hk, 毋須額外設定。

每個方法都用得着

用戶端只涵蓋可直接以 API 密鑰呼叫的端點 —— 不會出現「有這個方法但呼叫必定失敗」。密鑰的建立與撤銷只接受登入身分(一條外洩的密鑰不應該可以自我複製), 因此不在用戶端範圍內,請於主控台管理。

02TypeScript

TypeScript

import { LexiconClient, LexiconApiError } from './sdk/typescript';

const api = new LexiconClient({ apiKey: process.env.WRITERHK_API_KEY });

// 押「心」韻 × 悲傷 × 兩字 × 碼 33
const res = await api.searchWords({
  code: '33',
  rhyme_char: '心',
  emotion: '悲傷',
  length: 2,
  limit: 10,
});

console.log(res.total, res.words.map((w) => w.char));
// 28  [ '傷心', '傷感', '坎坎', '堵心', '失枕', ... ]

全部參數都有 JSDoc 註解(由規格描述帶入),編輯器會直接提示code 的比對規則、theme_scope 的三個值等等。

其他常用呼叫

await api.getSynonyms({ word: '孤獨', code: '22', limit: 10 });
await api.browseFacets({ category: 'noun.plant', emotion: '悲傷', length: 2 });
await api.annotateText({ text: '夜色靜靜落在窗前' });
await api.fixContour({ line: '風吹過山崗', moves: '=-+-' });
await api.getUsage();

// 路徑參數係第一個位置參數，查詢參數先擺喺物件裏面
await api.getWordCard('孤獨', { relations_limit: 10 });
await api.categoryWords('noun.plant', { emotion: '悲傷', length: 2 });
await api.getHomophones('心');

03Python

Python

from lexicon_client import LexiconClient, LexiconApiError

api = LexiconClient(api_key=os.environ["WRITERHK_API_KEY"])

res = api.search_words(code="33", rhyme_char="心", emotion="悲傷", length=2, limit=10)
print(res["total"], [w["char"] for w in res["words"]])
# 28 ['傷心', '傷感', '坎坎', '堵心', '失枕', ...]

# 換字:意思接近「孤獨」，且兩字皆為低平
syn = api.get_synonyms(word="孤獨", code="22", limit=10)
print([w["char"] for w in syn["words"]])
# ['寂寞', '獨自', '落寞']

方法名為 snake_case,全部參數皆為 keyword-only,回應為原始 dict。可傳入自己的 requests.Session 以共用連線池與逾時設定。

04錯誤處理

非 2xx 一律拋 LexiconApiError,帶 status、detail與 retryAfter(來自 Retry-After 標頭)。

TypeScript

try {
  await api.searchWords({ code: '33', limit: 10 });
} catch (e) {
  if (e instanceof LexiconApiError && e.isRateLimited) {
    // 429 有兩種:退避 60 秒係速率,3600 秒係當日配額用盡
    if ((e.retryAfter ?? 0) > 300) throw new Error('daily quota exhausted');
    await new Promise((r) => setTimeout(r, (e.retryAfter ?? 60) * 1000));
  } else {
    throw e;
  }
}

SDK 不會自動重試

退避策略與你的服務等級有關,交由呼叫方決定比較合理。可重試與不可重試的判斷,見錯誤處理與重試。

05自行生成

規格可直接取得,用你慣用的產生器產出任何語言的用戶端:

shell

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

此規格只含對外產品面(/api/lexicon/*);網站內部端點與帳戶管理不會外露。逐個端點的參數與回應,見API 參考。