Lingara Lingara Tài liệu Cẩm nang API Thư viện Ứng dụng Tạo Ứng dụng web
Ngôn ngữ: Tiếng Việt

Gửi một lượt cho gia sư

Phiên bản API 2026-10-affable-towhee

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

Gửi một tin nhắn đến gia sư và truyền phát câu trả lời dưới dạng các sự kiện delta, kết thúc bằng done. Không có gì được lưu lại: hãy gửi cuộc trò chuyện gần đây trong history, tối đa 20 mục. character và situation thiết lập bối cảnh. Yêu cầu gói trả phí.

Phạm vi tutor:converse

Tham số

Lingara-Versionheaderstringtùy chọn
Phiên bản API dùng để trả lời yêu cầu này. Nếu không có, token truy cập nhận phiên bản mà ứng dụng khách của nó được gắn, còn yêu cầu không có token nhận phiên bản hiện tại. Phiên bản đang phát triển chỉ có thể dùng bằng cách nêu tên nó ở đây. Phiên bản không xác định được trả lời bằng 400 với mã api_version_unknown. GET /v1/versions liệt kê các phiên bản.

Nội dung yêu cầu application/json

messagestringbắt buộc
historyarray of TurnEntrytùy chọn
roleTurnRolebắt buộc
contentstringbắt buộc
source_langstringbắt buộc
target_langstringbắt buộc
levelinteger | nulltùy chọn
characterstring | nulltùy chọn
situationstring | nulltùy chọn

Phản hồi

200 Câu trả lời của gia sư, từng phần một

Sự kiện luồng text/event-stream

Không gửi chú thích keepalive.

delta TurnDelta
textstringbắt buộc
notice Notice
codestringbắt buộc
messagestringbắt buộc
done Done Kết thúc luồng
error StreamError Kết thúc luồng

Đến bên trong phản hồi 200. Dòng trạng thái đã được gửi, nên lỗi xảy ra sau khi luồng mở được báo bằng sự kiện này.

codestringbắt buộc
messagestringbắt buộc
plan_idstring | nulltùy chọn

Lỗi

402application/json
Lệnh gọi của một ứng dụng khách tính phí theo mức dùng đã bị từ chối trước khi tiêu bất cứ thứ gì. spend_cap_reached: ứng dụng khách hoặc tài khoản của nó đã chạm hạn mức chi tiêu hằng tháng; hãy nâng hạn mức trên trang Tích hợp. metered_billing_inactive: tính phí theo mức dùng chưa được kích hoạt cho tài khoản này; hãy thiết lập hoặc cập nhật phương thức thanh toán trên trang Tích hợp.
410application/json
Phiên bản API dùng để trả lời yêu cầu này đã bị ngừng. Hãy gửi một phiên bản được hỗ trợ trong Lingara-Version, hoặc gắn ứng dụng khách với một phiên bản khác.
4XXapplication/json
Yêu cầu đã bị từ chối. code cho biết lý do, và error diễn đạt lý do đó bằng lời.
503application/json · text/plain
Dịch vụ tạm thời không khả dụng; hãy thử lại sau số giây ghi trong Retry-After. Trong thời gian bảo trì, phần thân là văn bản thuần thay vì phong bì lỗi.
5XXapplication/json
Yêu cầu đã bị từ chối. code cho biết lý do, và error diễn đạt lý do đó bằng lời.
codestringbắt buộc

Lý do yêu cầu bị từ chối, dưới dạng một mã ổn định để rẽ nhánh: ví dụ insufficient_scope (403), rate_limited (429) và, với ứng dụng khách tính phí theo mức dùng, spend_cap_reached (402) và metered_billing_inactive (402).

errorstringbắt buộc

Ví dụ

Ngôn ngữ của mã mẫu

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

Muốn dùng thư viện? Xem mục Thư viện.

Luồng ví dụ

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

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

event: done
data: {}

Nếu bản dịch và tài liệu tham chiếu tiếng Anh khác nhau, tài liệu tham chiếu tiếng Anh là bản đúng.