Generar una lista de vocabulario

Versión de la API 2026-10-affable-towhee

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

Transmite una lista de palabras al nivel solicitado. El flujo envía started con los detalles de la lista, un evento item por palabra y luego done. Hasta que la lista está lista, solo envía comentarios keepalive.

Ámbitos vocab:generate

Parámetros

Lingara-Versionheaderstringopcional: La versión de la API con la que se responde a esta solicitud. Sin ella, un token de acceso recibe la versión a la que está vinculado su cliente, y una solicitud sin token recibe la versión actual. La versión aún en desarrollo solo se alcanza nombrándola aquí. Una versión desconocida responde 400 con el código api_version_unknown. GET /v1/versions enumera las versiones.

Cuerpo de la solicitud `application/json`

levelintegerobligatorio
source_langstringobligatorio
target_langstringobligatorio
countinteger | nullopcional

Respuestas

200 La lista, una palabra por evento

Eventos del flujo `text/event-stream`

Envía un comentario keepalive cada 15 segundos.

started VocabStarted

metaVocabMetaobligatorio

levelintegerobligatorio
source_langstringobligatorio
target_langstringobligatorio
frameworkstringobligatorio
countintegerobligatorio
ai_generatedbooleanobligatorio

item VocabItem

wordstringobligatorio

pronunciationstring | nullopcional

readingstring | nullopcional

translationstringobligatorio

exampleVocabExample | nullopcional

sentencestringobligatorio
translationstringobligatorio

image_urlstring | nullopcional

done Done Termina el flujo

error StreamError Termina el flujo

Llega dentro de la respuesta 200. La línea de estado ya se ha enviado, así que un fallo después de abrirse el flujo se notifica como este evento.

codestringobligatorio
messagestringobligatorio
plan_idstring | nullopcional

Errores

402application/json: Se rechazó la llamada de un cliente con facturación por uso antes de que gastara nada. spend_cap_reached: el cliente o su cuenta ha alcanzado su límite de gasto mensual; sube el límite en la página Integraciones. metered_billing_inactive: la facturación por uso no está activa para esta cuenta; configúrala o actualiza el método de pago en la página Integraciones.
410application/json: La versión de la API con la que se responde a esta solicitud se ha retirado. Envía una versión admitida en Lingara-Version o vincula el cliente a otra versión.
4XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.
503application/json · text/plain: El servicio no está disponible temporalmente; vuelve a intentarlo tras el número de segundos indicado en Retry-After. Durante el mantenimiento, el cuerpo es texto sin formato en lugar del sobre de error.
5XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.

codestringobligatorio: Por qué se rechazó la solicitud, como un código estable con el que ramificar: por ejemplo insufficient_scope (403), rate_limited (429) y, para un cliente con facturación por uso, spend_cap_reached (402) y metered_billing_inactive (402).
errorstringobligatorio

Ejemplo

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

¿Prefieres una biblioteca? Consulta la sección Bibliotecas.

Ejemplo de flujo

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

Si una traducción y la referencia en inglés difieren, prevalece la referencia en inglés.