Guida rapida

Versione API 2026-10-affable-towhee

Cinque passaggi da zero a un elenco di vocaboli in streaming: crea un client, mettilo nella tua shell, scambialo con un token di accesso, esegui una chiamata e ottieni un nuovo token quando scade.

1. Crea un client

Nella pagina Integrazioni dell'app web di Lingara, all'indirizzo app.getlingara.com/admin, sotto Client OAuth, crea un client a cui è consentito «Genera vocabolario» (lo scope vocab:generate). Copia il suo ID client e il suo segreto. Il segreto viene mostrato una sola volta.

2. Mettilo nella tua shell

Salva l'ID client e il segreto nelle variabili d'ambiente LINGARA_CLIENT_ID e LINGARA_CLIENT_SECRET, così nessun segreto viene mai scritto in un comando.

export LINGARA_CLIENT_ID="<your client id>"
export LINGARA_CLIENT_SECRET="<your client secret>"

3. Ottieni un token di accesso

Questo comando scambia il client con un token di accesso e lo conserva in LINGARA_TOKEN, che ogni esempio di questo riferimento legge. Richiede jq e curl 7.76 o successivo. Se lo scambio fallisce, il comando stampa il codice di errore (per esempio invalid_client: controlla l'ID e il segreto) e lascia LINGARA_TOKEN vuoto, quindi la chiamata successiva fallisce con 401 finché uno scambio non riesce. Senza jq, esegui lo scambio descritto nella guida Autenticazione e copia a mano access_token dalla risposta.

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. Genera un elenco di vocaboli

Esegui questo comando. -N disattiva il buffering di curl, così ogni evento viene stampato appena arriva.

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}'

Cosa dovresti vedere

Un evento started con i dettagli dell'elenco, un evento item per ogni parola, poi done. Le tue parole saranno diverse da quelle di questo esempio.

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. Quando l'ora è scaduta

La chiamata risponde 401. Esegui di nuovo il passaggio 3. Se ora il passaggio 3 fallisce, il client o il suo segreto è cambiato nella pagina Integrazioni. Un programma segue la regola della guida Autenticazione: scambiare di nuovo una volta per ogni 401, e fermarsi se lo scambio fallisce.

In caso di discrepanza tra una traduzione e il riferimento in inglese, fa fede il riferimento in inglese.