Generate a vocabulary list

API version 2026-10-affable-towhee

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

Streams a list of words at the requested level. The stream sends started with the list's details, one item event per word, then done. Until the list is ready it sends keepalive comments only.

Scopes vocab:generate

Parameters

Lingara-Versionheaderstringoptional: The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers 400 with code api_version_unknown. GET /v1/versions lists the versions.

Request body `application/json`

levelintegerrequired
source_langstringrequired
target_langstringrequired
countinteger | nulloptional

Responses

200 The list, one word per event

Stream events `text/event-stream`

Sends a keepalive comment every 15 seconds.

started VocabStarted

metaVocabMetarequired

levelintegerrequired
source_langstringrequired
target_langstringrequired
frameworkstringrequired
countintegerrequired
ai_generatedbooleanrequired

item VocabItem

wordstringrequired

pronunciationstring | nulloptional

readingstring | nulloptional

translationstringrequired

exampleVocabExample | nulloptional

sentencestringrequired
translationstringrequired

image_urlstring | nulloptional

done Done Ends the stream

error StreamError Ends the stream

Arrives inside the 200 response. The status line has already been sent, so a failure after the stream opens is reported as this event.

codestringrequired
messagestringrequired
plan_idstring | nulloptional

Errors

402application/json: A metered client's call was refused before it spent anything. spend_cap_reached: the client or its account has reached its monthly spending limit; raise the limit on the Integrations page. metered_billing_inactive: usage billing is not active for this account; set it up, or update the payment method, on the Integrations page.
410application/json: The API version this request is answered under has been discontinued. Send a supported version in Lingara-Version, or re-pin the client.
4XXapplication/json: The request was refused. code says why, and error says it in words.
503application/json · text/plain: The service is temporarily unavailable; retry after the number of seconds in Retry-After. During maintenance the body is plain text rather than the error envelope.
5XXapplication/json: The request was refused. code says why, and error says it in words.

codestringrequired: Why the request was refused, as a stable code to branch on: for example insufficient_scope (403), rate_limited (429) and, for a metered client, spend_cap_reached (402) and metered_billing_inactive (402).
errorstringrequired

Example

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";
    }
}

Prefer a library? See the Libraries section.

Example stream

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