Kirim peristiwa

Versi API 2026-10-affable-towhee

post https://api.getlingara.com/v1/events

Memberi tahu Lingara apa yang terjadi di game Anda, misalnya pelajar memasuki tempat baru. Peristiwa dicatat sekali dan dijawab dengan 202. Dengan generate: true Lingara juga memulai rencana pelajaran, yang memerlukan lesson_plans:write serta dibatasi dan ditagih seperti POST /v1/lesson-plans: reaction menyebut rencananya, lalu menyusul lesson_plan.ready atau lesson_plan.failed. Gambarkan dunianya, jangan pernah nama atau obrolan pemain.

Cakupan events:write

Parameter

Lingara-Versionheaderstringopsional: Versi API yang digunakan untuk menjawab permintaan ini. Tanpanya, token akses mendapatkan versi yang disematkan pada kliennya, dan permintaan tanpa token mendapatkan versi saat ini. Versi yang masih dalam pengembangan hanya dapat dicapai dengan menyebutkannya di sini. Versi yang tidak dikenal dijawab 400 dengan kode api_version_unknown. GET /v1/versions mencantumkan versi-versinya.
Idempotency-Keyheaderstringwajib: Nilai yang Anda pilih untuk setiap peristiwa dan gunakan lagi saat mencoba ulang: 1 sampai 255 karakter ASCII yang terlihat, misalnya UUID. Percobaan ulang dengan kunci yang sama mendapatkan jawaban pertama dan tidak ditagih lagi, meskipun isinya berbeda. Tanpa kunci yang valid, permintaan dijawab 400 dengan kode idempotency_key_required.

Isi permintaan `application/json`

typestringwajib

dataWorldPracticeRequestedwajib

topicstringwajib
source_langstringwajib
target_langstringwajib
levelintegerwajib
tagsarray of stringopsional
generateboolean | nullopsional

Respons

202 Peristiwa sudah dicatat

idstringwajib

typestringwajib

created_atstringwajib

reactionReactionReport | nullopsional

statusReactionStatuswajib
plan_idstring | nullopsional
plan_statusPlanStatus | nullopsional: Status rencana saat peristiwa diterima. Hanya generating yang menjanjikan bahwa lesson_plan.ready atau lesson_plan.failed akan menyusul. Nilai lain berarti rencana dari perpustakaan, yang dapat Anda baca sekarang dengan GET /v1/lesson-plans/{id}.
codestring | nullopsional
errorstring | nullopsional

Galat

402application/json: Panggilan klien dengan penagihan per pemakaian ditolak sebelum menghabiskan apa pun. spend_cap_reached: klien atau akunnya telah mencapai batas pengeluaran bulanannya; naikkan batasnya di halaman Integrasi. metered_billing_inactive: penagihan per pemakaian tidak aktif untuk akun ini; siapkan, atau perbarui metode pembayarannya, di halaman Integrasi.
410application/json: Versi API yang digunakan untuk menjawab permintaan ini telah dihentikan. Kirim versi yang didukung di Lingara-Version, atau sematkan klien ke versi lain.
4XXapplication/json: Permintaan ditolak. code menyebutkan alasannya, dan error menjelaskannya dengan kata-kata.
503application/json · text/plain: Layanan sementara tidak tersedia; coba lagi setelah jumlah detik di Retry-After. Selama pemeliharaan, isi respons berupa teks biasa, bukan amplop galat.
5XXapplication/json: Permintaan ditolak. code menyebutkan alasannya, dan error menjelaskannya dengan kata-kata.

codestringwajib: Alasan permintaan ditolak, sebagai kode tetap untuk percabangan: misalnya insufficient_scope (403), rate_limited (429) dan, untuk klien dengan penagihan per pemakaian, spend_cap_reached (402) dan metered_billing_inactive (402).
errorstringwajib

Contoh

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

Lebih suka pustaka? Lihat bagian Pustaka.