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

Tạo danh sách từ vựng

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

post https://api.getlingara.com/v1/vocab/stream

Truyền phát danh sách từ ở trình độ được yêu cầu. Luồng gửi started kèm thông tin chi tiết của danh sách, một sự kiện item cho mỗi từ, rồi done. Cho đến khi danh sách sẵn sàng, luồng chỉ gửi các chú thích keepalive.

Phạm vi vocab:generate

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

levelintegerbắt buộc
source_langstringbắt buộc
target_langstringbắt buộc
countinteger | nulltùy chọn

Phản hồi

200 Danh sách, mỗi sự kiện một từ

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

Gửi một chú thích keepalive mỗi 15 giây.

started VocabStarted
metaVocabMetabắt buộc
levelintegerbắt buộc
source_langstringbắt buộc
target_langstringbắt buộc
frameworkstringbắt buộc
countintegerbắt buộc
ai_generatedbooleanbắt buộc
item VocabItem
wordstringbắt buộc
pronunciationstring | nulltùy chọn
readingstring | nulltùy chọn
translationstringbắt buộc
exampleVocabExample | nulltùy chọn
sentencestringbắt buộc
translationstringbắt buộc
image_urlstring | nulltùy chọn
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/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";
    }
}

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

Luồng ví dụ

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

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.