Lingara Lingara المستندات أدلة التعلّم API المكتبات التطبيقات البناء تطبيق الويب
اللغة: العربية

إنشاء قائمة مفردات

إصدار API 2026-10-affable-towhee

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

يبثّ قائمة كلمات بالمستوى المطلوب. يرسل البث started مع تفاصيل القائمة، وحدث item واحدًا لكل كلمة، ثم done. وإلى أن تصبح القائمة جاهزة، لا يرسل سوى تعليقات keepalive.

النطاقات vocab:generate

المعاملات

Lingara-Versionheaderstringاختياري
إصدار API الذي يُجاب عن هذا الطلب به. بدونه، يحصل رمز الوصول على الإصدار الذي رُبط به عميله، ويحصل الطلب الذي لا رمز مميز فيه على الإصدار الحالي. لا يمكن الوصول إلى الإصدار الذي لا يزال قيد التطوير إلا بذكره هنا. الإصدار غير المعروف يُجاب عنه بـ 400 مع الرمز api_version_unknown. يسرد GET /v1/versions الإصدارات.

متن الطلب application/json

levelintegerمطلوب
source_langstringمطلوب
target_langstringمطلوب
countinteger | nullاختياري

الاستجابات

200 القائمة، كلمة واحدة لكل حدث

أحداث البث text/event-stream

يرسل تعليق إبقاء الاتصال (keepalive) كل 15 ثانية.

started VocabStarted
metaVocabMetaمطلوب
levelintegerمطلوب
source_langstringمطلوب
target_langstringمطلوب
frameworkstringمطلوب
countintegerمطلوب
ai_generatedbooleanمطلوب
item VocabItem
wordstringمطلوب
pronunciationstring | nullاختياري
readingstring | nullاختياري
translationstringمطلوب
exampleVocabExample | nullاختياري
sentencestringمطلوب
translationstringمطلوب
image_urlstring | nullاختياري
done Done ينهي البث
error StreamError ينهي البث

يصل داخل استجابة 200. سطر الحالة أُرسل بالفعل، لذا يُبلَّغ عن أي فشل بعد فتح البث على أنه هذا الحدث.

codestringمطلوب
messagestringمطلوب
plan_idstring | nullاختياري

الأخطاء

402application/json
رُفض استدعاء عميل يُفوتَر بحسب الاستهلاك قبل أن يُنفق أي شيء. spend_cap_reached: بلغ العميل أو حسابه حدّ الإنفاق الشهري؛ ارفع الحد في صفحة عمليات التكامل. metered_billing_inactive: الفوترة بحسب الاستهلاك غير مفعّلة لهذا الحساب؛ فعّلها أو حدّث طريقة الدفع في صفحة عمليات التكامل.
410application/json
تم إيقاف إصدار API الذي يُجاب عن هذا الطلب به. أرسل إصدارًا مدعومًا في Lingara-Version، أو اربط العميل بإصدار آخر.
4XXapplication/json
رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.
503application/json · text/plain
الخدمة غير متاحة مؤقتًا؛ أعد المحاولة بعد عدد الثواني المذكور في Retry-After. أثناء الصيانة يكون المتن نصًا عاديًا بدلًا من غلاف الخطأ.
5XXapplication/json
رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.
codestringمطلوب

سبب رفض الطلب، في صورة رمز ثابت يمكن التفرّع بناءً عليه: مثل insufficient_scope (403) وrate_limited (429)، ولعميل يُفوتَر بحسب الاستهلاك spend_cap_reached (402) وmetered_billing_inactive (402).

errorstringمطلوب

مثال

لغة مثال الشيفرة

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

Go

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

تفضّل مكتبة؟ راجع قسم المكتبات.

مثال على البث

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

إذا اختلفت ترجمةٌ عن المرجع الإنجليزي، فالمرجع الإنجليزي هو الصحيح.