快速入门

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 就重新换取一次，如果换取失败则停止。

如译文与英文参考文档不一致，以英文参考文档为准。