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

هر 15 ثانیه یک یادداشت keepalive می‌فرستد.

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

اگر ترجمه با مرجع انگلیسی فرق داشته باشد، مرجع انگلیسی درست است.