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

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