Lähetä tapahtuma

API-versio 2026-10-affable-towhee

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

Kertoo Lingaralle, mitä pelissäsi tapahtui, esimerkiksi että oppija saapuu uuteen paikkaan. Tapahtuma tallennetaan kerran, ja siihen vastataan 202. Kun mukana on generate: true, Lingara aloittaa myös tuntisuunnitelman, joka vaatii lesson_plans:write ja jota rajoitetaan ja laskutetaan kuten POST /v1/lesson-plans: reaction nimeää suunnitelman, ja sen jälkeen tulee lesson_plan.ready tai lesson_plan.failed. Kuvaa maailmaa, älä koskaan pelaajan nimeä tai keskusteluja.

Oikeuslaajuudet events:write

Parametrit

Lingara-Versionheaderstringvalinnainen: API-versio, jolla tähän pyyntöön vastataan. Ilman sitä käyttötunnus saa version, johon sen asiakas on kiinnitetty, ja pyyntö ilman tunnusta saa nykyisen version. Vielä kehitteillä olevaan versioon pääsee vain nimeämällä sen tässä. Tuntemattomaan versioon vastataan 400 koodilla api_version_unknown. GET /v1/versions luettelee versiot.
Idempotency-Keyheaderstringpakollinen: Arvo, jonka valitset kullekin tapahtumalle ja lähetät uudelleen, kun yrität uudestaan: 1–255 näkyvää ASCII-merkkiä, esimerkiksi UUID. Uusintayritys samalla avaimella saa ensimmäisen vastauksen eikä sitä laskuteta uudelleen, vaikka sen sisältö eroaisi. Ilman kelvollista avainta pyyntöön vastataan 400 koodilla idempotency_key_required.

Pyynnön runko `application/json`

typestringpakollinen

dataWorldPracticeRequestedpakollinen

topicstringpakollinen
source_langstringpakollinen
target_langstringpakollinen
levelintegerpakollinen
tagsarray of stringvalinnainen
generateboolean | nullvalinnainen

Vastaukset

202 Tapahtuma on tallennettu

idstringpakollinen

typestringpakollinen

created_atstringpakollinen

reactionReactionReport | nullvalinnainen

statusReactionStatuspakollinen
plan_idstring | nullvalinnainen
plan_statusPlanStatus | nullvalinnainen: Suunnitelman tila, kun tapahtuma hyväksyttiin. Vain generating lupaa, että lesson_plan.ready tai lesson_plan.failed seuraa. Mikä tahansa muu arvo on kirjastosta tarjottu suunnitelma, jonka voit lukea heti osoitteesta GET /v1/lesson-plans/{id}.
codestring | nullvalinnainen
errorstring | nullvalinnainen

Virheet

402application/json: Käytön mukaan laskutettavan asiakkaan kutsu hylättiin ennen kuin se kulutti mitään. spend_cap_reached: asiakas tai sen tili on saavuttanut kuukausittaisen kulutusrajansa; nosta rajaa Integraatiot-sivulla. metered_billing_inactive: käytön mukainen laskutus ei ole tällä tilillä käytössä; ota se käyttöön tai päivitä maksutapa Integraatiot-sivulla.
410application/json: API-versio, jolla tähän pyyntöön vastataan, on lopetettu. Lähetä tuettu versio Lingara-Version-otsakkeessa tai kiinnitä asiakas toiseen versioon.
4XXapplication/json: Pyyntö hylättiin. code kertoo syyn, ja error kertoo sen sanoin.
503application/json · text/plain: Palvelu ei ole tilapäisesti käytettävissä; yritä uudelleen Retry-After-otsakkeen ilmoittaman sekuntimäärän jälkeen. Huoltokatkon aikana runko on pelkkää tekstiä virhekehyksen sijaan.
5XXapplication/json: Pyyntö hylättiin. code kertoo syyn, ja error kertoo sen sanoin.

codestringpakollinen: Miksi pyyntö hylättiin, pysyvänä koodina, jonka mukaan voit haarautua: esimerkiksi insufficient_scope (403), rate_limited (429) ja käytön mukaan laskutettavalle asiakkaalle spend_cap_reached (402) ja metered_billing_inactive (402).
errorstringpakollinen

Esimerkki

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}}'

Käytätkö mieluummin kirjastoa? Katso Kirjastot-osio.