快速入門

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 就重新換一擺，換取失敗就停落來。

若是翻譯佮英文參考文件無仝，就以英文參考文件為準。