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

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