快速入門

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 就重新換取一次，如果換取失敗則停止。

如譯文與英文參考文件有出入，以英文參考文件為準。