Lingara Lingara مستندات رهنماها API کتابخانه‌ها اپلیکیشن‌ها ساختن اپلیکیشن وب
زبان: دری

فرستادن یک نوبت به معلم خصوصی

نسخهٔ API 2026-10-affable-towhee

post https://api.getlingara.com/v1/tutor/message

یک پیام به معلم خصوصی می‌فرستد و پاسخ را به صورت رویدادهای delta به شکل جریانی برمی‌گرداند که با done پایان می‌یابد. هیچ چیزی ذخیره نمی‌شود: گفتگوی اخیر را در history بفرستید، حداکثر ۲۰ مورد. character و situation صحنه را تعیین می‌کنند. به اشتراک پولی نیاز دارد.

حوزه‌های دسترسی tutor:converse

پارامترها

Lingara-Versionheaderstringاختیاری
نسخهٔ API‌ای که این درخواست با آن جواب داده می‌شود. بدون آن، توکن دسترسی نسخه‌ای را می‌گیرد که کلاینت آن به آن وصل است، و درخواستی بدون توکن نسخهٔ فعلی را می‌گیرد. به نسخه‌ای که هنوز در حال انکشاف است تنها با نام‌بردن آن در اینجا می‌توان رسید. نسخهٔ ناشناخته با 400 و کد api_version_unknown جواب داده می‌شود. GET /v1/versions نسخه‌ها را فهرست می‌کند.

بدنهٔ درخواست application/json

messagestringضروری
historyarray of TurnEntryاختیاری
roleTurnRoleضروری
contentstringضروری
source_langstringضروری
target_langstringضروری
levelinteger | nullاختیاری
characterstring | nullاختیاری
situationstring | nullاختیاری

پاسخ‌ها

200 پاسخ معلم خصوصی، بخش به بخش

رویدادهای جریان text/event-stream

هیچ یادداشت keepalive نمی‌فرستد.

delta TurnDelta
textstringضروری
notice Notice
codestringضروری
messagestringضروری
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/tutor/message" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"我要两斤荔枝。","history":[{"role":"assistant","content":"欢迎!今天的荔枝很新鲜。"}],"source_lang":"en","target_lang":"zh","level":2,"character":"a fruit seller in a night market","situation":"buying lychees, haggling"}'

TypeScript

const reply = client.sendTutorMessage({
  message: "你好!我想点一杯茶。",
  history: [],
  source_lang: "en",
  target_lang: "zh",
});
for await (const ev of reply) {
  if (ev.event === "delta") process.stdout.write(ev.data.text);
}

Rust

use lingara::models::{SendTutorMessageEvent, TutorTurnRequest};

let request = TutorTurnRequest {
    message: "你好!我想点一杯茶。".into(),
    history: Vec::new(),
    source_lang: "en".into(),
    target_lang: "zh".into(),
    level: None,
    character: None,
    situation: None,
};
let mut reply = client.send_tutor_message(&request).await?;
while let Some(event) = reply.next().await {
    if let SendTutorMessageEvent::Delta(delta) = event? {
        print!("{}", delta.text);
    }
}

Go

s, err := client.SendTutorMessage(ctx, lingara.TutorTurnRequest{
	Message:    "你好!我想点一杯茶。",
	SourceLang: "en",
	TargetLang: "zh",
})
if err != nil {
	return err
}
defer s.Close()
for ev, err := range s.Events() {
	if err != nil {
		return err
	}
	if delta, ok := ev.(lingara.SendTutorMessageEventDelta); ok {
		fmt.Print(delta.Data.Text)
	}
}

Java

import com.getlingara.client.model.SendTutorMessageEvent;
import com.getlingara.client.model.TutorTurnRequest;

TutorTurnRequest turn =
    new TutorTurnRequest().message("荔枝多少钱?").sourceLang("en").targetLang("zh").level(2);
try (EventStream<SendTutorMessageEvent> stream = client.sendTutorMessage(turn)) {
  for (SendTutorMessageEvent event : stream) {
    if (event instanceof SendTutorMessageEvent.Delta delta) {
      System.out.print(delta.data().getText());
    } else if (event instanceof SendTutorMessageEvent.Notice notice) {
      System.out.println("\n(" + notice.data().getMessage() + ")");
    }
  }
}

Kotlin

import com.getlingara.kotlin.LingaraClient
import com.getlingara.kotlin.model.SendTutorMessageEvent
import com.getlingara.kotlin.model.TutorTurnRequest

val turn = TutorTurnRequest(message = "荔枝多少钱?", sourceLang = "en", targetLang = "zh", level = 2)
client.sendTutorMessage(turn).use { stream ->
    stream.collect { event ->
        when (event) {
            is SendTutorMessageEvent.Delta -> print(event.data.text)
            is SendTutorMessageEvent.Notice -> println("\n(${event.data.message})")
        }
    }
}

Ruby

history = [{role: "user", content: "你好"}, {role: "assistant", content: "你好!你想练习什么?"}]
client.send_tutor_message(message: "我想点菜", history: history, source_lang: "en", target_lang: "zh") do |event|
  case event
  in Lingara::SendTutorMessageEventDelta => delta then print delta.data.text
  in Lingara::SendTutorMessageEventNotice => notice then warn notice.data.message
  else nil
  end
end
puts

PHP

use Lingara\Model\TutorTurnRequest;
use Lingara\Stream\SendTutorMessageEvent;

$turn = new TutorTurnRequest(['message' => '荔枝多少钱?', 'source_lang' => 'en', 'target_lang' => 'zh', 'level' => 2]);
foreach ($client->sendTutorMessage($turn) as $event) {
    if ($event instanceof SendTutorMessageEvent\Delta) {
        echo $event->data->getText();
    } elseif ($event instanceof SendTutorMessageEvent\Notice) {
        echo "\n(", $event->data->getMessage(), ')';
    }
}
echo "\n";

کتابخانه را ترجیح می‌دهید؟ بخش کتابخانه‌ها را ببینید.

نمونهٔ جریان

event: delta
data: {"text":"两斤荔枝,"}

event: delta
data: {"text":"一共三十块。"}

event: done
data: {}

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