Générer une liste de vocabulaire

Version de l'API 2026-10-affable-towhee

post https://api.getlingara.com/v1/vocab/stream

Diffuse en flux une liste de mots au niveau demandé. Le flux envoie started avec les détails de la liste, un événement item par mot, puis done. Tant que la liste n'est pas prête, il n'envoie que des commentaires keepalive.

Portées vocab:generate

Paramètres

Lingara-Versionheaderstringfacultatif: La version de l'API sous laquelle traiter cette requête. Sans elle, un jeton d'accès obtient la version à laquelle son client est rattaché, et une requête sans jeton obtient la version actuelle. La version encore en développement ne s'atteint qu'en la nommant ici. Une version inconnue répond 400 avec le code api_version_unknown. GET /v1/versions liste les versions.

Corps de la requête `application/json`

levelintegerobligatoire
source_langstringobligatoire
target_langstringobligatoire
countinteger | nullfacultatif

Réponses

200 La liste, un mot par événement

Événements du flux `text/event-stream`

Envoie un commentaire keepalive toutes les 15 secondes.

started VocabStarted

metaVocabMetaobligatoire

levelintegerobligatoire
source_langstringobligatoire
target_langstringobligatoire
frameworkstringobligatoire
countintegerobligatoire
ai_generatedbooleanobligatoire

item VocabItem

wordstringobligatoire

pronunciationstring | nullfacultatif

readingstring | nullfacultatif

translationstringobligatoire

exampleVocabExample | nullfacultatif

sentencestringobligatoire
translationstringobligatoire

image_urlstring | nullfacultatif

done Done Termine le flux

error StreamError Termine le flux

Arrive dans la réponse 200. La ligne d'état a déjà été envoyée, donc un échec survenu après l'ouverture du flux est signalé par cet événement.

codestringobligatoire
messagestringobligatoire
plan_idstring | nullfacultatif

Erreurs

402application/json: L'appel d'un client facturé à l'usage a été refusé avant qu'il ne dépense quoi que ce soit. spend_cap_reached : le client ou son compte a atteint sa limite de dépenses mensuelle ; relevez la limite sur la page Intégrations. metered_billing_inactive : la facturation à l'usage n'est pas active pour ce compte ; configurez-la ou mettez à jour le moyen de paiement sur la page Intégrations.
410application/json: La version de l'API sous laquelle cette requête est traitée a été retirée. Envoyez une version prise en charge dans Lingara-Version, ou rattachez le client à une autre version.
4XXapplication/json: La requête a été refusée. code indique pourquoi, et error l'explique en toutes lettres.
503application/json · text/plain: Le service est temporairement indisponible ; réessayez après le nombre de secondes indiqué dans Retry-After. Pendant la maintenance, le corps est du texte brut plutôt que l'enveloppe d'erreur.
5XXapplication/json: La requête a été refusée. code indique pourquoi, et error l'explique en toutes lettres.

codestringobligatoire: Pourquoi la requête a été refusée, sous forme de code stable sur lequel brancher votre logique : par exemple insufficient_scope (403), rate_limited (429) et, pour un client facturé à l'usage, spend_cap_reached (402) et metered_billing_inactive (402).
errorstringobligatoire

Exemple

curlTypeScriptRustGoJavaKotlinRubyPHP

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

TypeScript

const stream = client.generateVocabulary({ level: 2, source_lang: "en", target_lang: "zh", count: 8 });
for await (const ev of stream) {
  if (ev.event === "item") console.log(ev.data.word, ev.data.translation);
}

Rust

use lingara::models::{GenerateVocabularyEvent, VocabRequest};
use std::num::NonZeroU8;

let request = VocabRequest { level: 2, source_lang: "en".into(), target_lang: "zh".into(), count: NonZeroU8::new(8) };
let mut stream = client.generate_vocabulary(&request).await?;
while let Some(event) = stream.next().await {
    if let GenerateVocabularyEvent::Item(item) = event? {
        println!("{} {}", item.word, item.translation);
    }
}

count := uint8(8)
s, err := client.GenerateVocabulary(ctx, lingara.VocabRequest{Level: 2, SourceLang: "en", TargetLang: "zh", Count: &count})
if err != nil {
	return err
}
defer s.Close()
for ev, err := range s.Events() {
	if err != nil {
		return err
	}
	if item, ok := ev.(lingara.GenerateVocabularyEventItem); ok {
		fmt.Println(item.Data.Word, item.Data.Translation)
	}
}

Java

import com.getlingara.client.model.GenerateVocabularyEvent;
import com.getlingara.client.model.VocabRequest;

VocabRequest request = new VocabRequest().level(2).sourceLang("en").targetLang("zh").count(8);
try (EventStream<GenerateVocabularyEvent> stream = client.generateVocabulary(request)) {
  for (GenerateVocabularyEvent event : stream) {
    if (event instanceof GenerateVocabularyEvent.Item item) {
      System.out.println(item.data().getWord() + " " + item.data().getTranslation());
    }
  }
}

Kotlin

import com.getlingara.kotlin.LingaraClient
import com.getlingara.kotlin.model.GenerateVocabularyEvent
import com.getlingara.kotlin.model.VocabRequest

val request = VocabRequest(level = 2, sourceLang = "en", targetLang = "zh", count = 8)
// The request is sent here; collect the stream once, inside use {}.
client.generateVocabulary(request).use { stream ->
    stream.collect { event ->
        when (event) {
            is GenerateVocabularyEvent.Item -> println("${event.data.word} ${event.data.translation}")
            is GenerateVocabularyEvent.Started -> Unit
        }
    }
}

Ruby

client.generate_vocabulary(level: 2, source_lang: "en", target_lang: "zh", count: 8) do |event|
  case event
  in Lingara::GenerateVocabularyEventItem => item then puts "#{item.data.word}: #{item.data.translation}"
  else nil
  end
end

PHP

use Lingara\Model\VocabRequest;
use Lingara\Stream\GenerateVocabularyEvent;

$request = new VocabRequest(['level' => 2, 'source_lang' => 'en', 'target_lang' => 'zh', 'count' => 8]);
foreach ($client->generateVocabulary($request) as $event) {
    if ($event instanceof GenerateVocabularyEvent\Item) {
        echo $event->data->getWord(), ': ', $event->data->getTranslation(), "\n";
    }
}

Vous préférez une bibliothèque ? Consultez la section Bibliothèques.

Exemple de flux

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: {}

En cas de divergence entre une traduction et la référence en anglais, la référence en anglais fait foi.