快速入門

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

假使翻譯㧯英文參考文件無共樣，就以英文參考文件為準。