Hantar peristiwa

Versi API 2026-10-affable-towhee

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

Memberitahu Lingara apa yang berlaku dalam permainan anda, contohnya pelajar memasuki tempat baharu. Peristiwa direkodkan sekali dan dijawab dengan 202. Dengan generate: true Lingara juga memulakan rancangan pelajaran, yang memerlukan lesson_plans:write dan dihadkan serta dibilkan seperti POST /v1/lesson-plans: reaction menamakan rancangan itu, dan kemudian lesson_plan.ready atau lesson_plan.failed menyusul. Gambarkan dunianya, jangan sekali-kali nama atau sembang pemain.

Skop events:write

Parameter

Lingara-Versionheaderstringpilihan: Versi API yang digunakan untuk menjawab permintaan ini. Tanpanya, token akses mendapat versi yang dipautkan kepada kliennya, dan permintaan tanpa token mendapat versi semasa. Versi yang masih dalam pembangunan hanya boleh dicapai dengan menamakannya di sini. Versi yang tidak dikenali dijawab 400 dengan kod api_version_unknown. GET /v1/versions menyenaraikan versi.
Idempotency-Keyheaderstringwajib: Nilai yang anda pilih untuk setiap peristiwa dan gunakan semula apabila mencuba lagi: 1 hingga 255 aksara ASCII yang kelihatan, seperti UUID. Cubaan semula dengan kunci yang sama menerima jawapan pertama dan tidak dibilkan lagi, walaupun kandungannya berbeza. Tanpa kunci yang sah, permintaan dijawab 400 dengan kod idempotency_key_required.

Kandungan permintaan `application/json`

typestringwajib

dataWorldPracticeRequestedwajib

topicstringwajib
source_langstringwajib
target_langstringwajib
levelintegerwajib
tagsarray of stringpilihan
generateboolean | nullpilihan

Respons

202 Peristiwa telah direkodkan

idstringwajib

typestringwajib

created_atstringwajib

reactionReactionReport | nullpilihan

statusReactionStatuswajib
plan_idstring | nullpilihan
plan_statusPlanStatus | nullpilihan: Status rancangan semasa peristiwa diterima. Hanya generating yang menjanjikan bahawa lesson_plan.ready atau lesson_plan.failed akan menyusul. Nilai lain ialah rancangan dari perpustakaan, yang boleh anda baca sekarang dengan GET /v1/lesson-plans/{id}.
codestring | nullpilihan
errorstring | nullpilihan

Ralat

402application/json: Panggilan klien bermeter telah ditolak sebelum ia membelanjakan apa-apa. spend_cap_reached: klien atau akaunnya telah mencapai had perbelanjaan bulanannya; naikkan had di halaman Integrasi. metered_billing_inactive: pengebilan bermeter tidak aktif untuk akaun ini; sediakannya, atau kemas kini kaedah pembayaran, di halaman Integrasi.
410application/json: Versi API yang digunakan untuk menjawab permintaan ini telah dihentikan. Hantar versi yang disokong dalam Lingara-Version, atau pautkan klien kepada versi lain.
4XXapplication/json: Permintaan ditolak. code menyatakan sebabnya, dan error menerangkannya dengan perkataan.
503application/json · text/plain: Perkhidmatan tidak tersedia buat sementara waktu; cuba lagi selepas bilangan saat dalam Retry-After. Semasa penyelenggaraan, kandungan ialah teks biasa dan bukan sampul ralat.
5XXapplication/json: Permintaan ditolak. code menyatakan sebabnya, dan error menerangkannya dengan perkataan.

codestringwajib: Sebab permintaan ditolak, sebagai kod stabil untuk dijadikan asas percabangan: contohnya insufficient_scope (403), rate_limited (429) dan, bagi klien bermeter, 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 bahagian Pustaka.