快速入門

API 版本 2026-10-affable-towhee

由零開始到攞到一份串流詞彙表，只需要五步：建立用戶端、放入你嘅 shell、用佢換一個存取權杖、調用一次，同埋喺權杖過期嗰陣攞個新嘅。

1. 建立用戶端

喺 Lingara 網頁應用程式嘅整合頁面（網址係 app.getlingara.com/admin）嘅 OAuth 用戶端下面，建立一個可以「產生詞彙」（權限範圍 vocab:generate）嘅用戶端。複製佢嘅用戶端 ID 同密鑰。密鑰只會顯示一次。

2. 放入你嘅 shell

將用戶端 ID 同密鑰分別儲存喺 LINGARA_CLIENT_ID 同 LINGARA_CLIENT_SECRET 環境變數，咁樣指令入面永遠唔會寫出密鑰。

export LINGARA_CLIENT_ID="<your client id>"
export LINGARA_CLIENT_SECRET="<your client secret>"

3. 攞存取權杖

呢個指令會用用戶端換一個存取權杖，然後保存喺 LINGARA_TOKEN，呢份參考入面每個例子都係由嗰度讀取。佢需要 jq 同 curl 7.76 或者更新嘅版本。如果換取失敗，指令會印出錯誤代碼（例如 invalid_client：請檢查 ID 同密鑰），並將 LINGARA_TOKEN 留空，所以喺換取成功之前，下一次調用都會以 401 失敗。冇 jq 嘅話，就執行驗證指南入面嗰個換取指令，再由回應度手動複製 access_token。

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

4. 生成詞彙表

執行呢個指令。-N 會關閉 curl 嘅緩衝，令每個事件一到就即刻顯示。

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

你應該見到嘅內容

一個附有清單詳情嘅 started 事件，每個詞一個 item 事件，跟住係 done。你攞到嘅詞語會同呢個例子唔同。

event: started
data: {"meta":{"level":2,"source_lang":"en","target_lang":"zh","framework":"HSK","count":2,"ai_generated":true}}

event: item
data: {"word":"你好","pronunciation":"nǐ hǎo","translation":"hello","example":{"sentence":"你好，我叫小明。","translation":"Hello, my name is Xiaoming."}}

event: item
data: {"word":"谢谢","pronunciation":"xiè xie","translation":"thank you"}

event: done
data: {}

5. 夠鐘之後

調用會傳回 401。請再執行第 3 步。如果第 3 步而家失敗，即係用戶端或者佢嘅密鑰已經喺整合頁面度改咗。程式要跟身份驗證指南嘅規則：每收到一次 401 就重新換一次，換取失敗就停低。

如果譯本同英文參考文件有出入，以英文參考文件為準。