Lingara Lingara 문서 학습 가이드 API 라이브러리 앱 만들기 웹 앱
언어: 한국어

튜터에게 한 턴 보내기

API 버전 2026-10-affable-towhee

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

튜터에게 메시지 하나를 보내고 답장을 delta 이벤트로 스트리밍하며, done으로 끝납니다. 아무것도 저장되지 않으므로 최근 대화를 history에 최대 20개 항목까지 보내세요. character와 situation으로 장면을 설정합니다. 유료 요금제가 필요합니다.

스코프 tutor:converse

매개변수

Lingara-Versionheaderstring선택
이 요청에 응답할 API 버전입니다. 지정하지 않으면 액세스 토큰은 해당 클라이언트에 고정된 버전을, 토큰이 없는 요청은 현재 버전을 받습니다. 개발 중인 버전은 여기에서 지정해야만 사용할 수 있습니다. 알 수 없는 버전에는 코드 api_version_unknown과 함께 400으로 응답합니다. 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: {}

번역본과 영어 참조 문서의 내용이 다른 경우, 영어 참조 문서가 올바른 것으로 봅니다.