クイックスタート

API バージョン 2026-10-affable-towhee

何もない状態から、ストリーミングされる単語リストまでの5ステップです。クライアントを作成し、シェルに設定し、アクセストークンと交換し、1回呼び出し、期限が切れたら新しいトークンを取得します。

1. クライアントを作成する

Lingara ウェブアプリの「連携」ページ(app.getlingara.com/admin)の「OAuth クライアント」で、「語彙を生成」ができるクライアント(スコープ vocab:generate)を作成します。クライアント ID とシークレットをコピーしてください。シークレットが表示されるのは一度だけです。

2. シェルに設定する

クライアント 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 イベント、単語ごとに1つの 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. 1時間が過ぎたら

呼び出しは 401 で応答します。ステップ3をもう一度実行してください。ステップ3が失敗するようになった場合は、「連携」ページでクライアントまたはそのシークレットが変更されています。プログラムは認証ガイドのルールに従います。401 のたびに一度だけ再度交換し、交換が失敗したら中止します。

翻訳と英語版リファレンスの内容が異なる場合は、英語版リファレンスが正しいものとします。