Olay gönder

API sürümü 2026-10-affable-towhee

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

Oyununuzda ne olduğunu Lingara'ya bildirir; örneğin öğrencinin yeni bir yere girmesi. Olay bir kez kaydedilir ve 202 ile yanıtlanır. generate: true ile Lingara bir ders planı da başlatır; bunun için lesson_plans:write gerekir ve sınırları ile faturalandırması POST /v1/lesson-plans ile aynıdır: reaction planı belirtir, ardından lesson_plan.ready veya lesson_plan.failed gelir. Dünyayı betimleyin, bir oyuncunun adını veya sohbetini asla göndermeyin.

Kapsamlar events:write

Parametreler

Lingara-Versionheaderstringisteğe bağlı: Bu isteğin yanıtlanacağı API sürümü. Belirtilmezse bir erişim token'ı istemcisinin bağlı olduğu sürümü, token içermeyen bir istek ise güncel sürümü alır. Hâlâ geliştirilmekte olan sürüme yalnızca burada adı verilerek ulaşılır. Bilinmeyen bir sürüm 400 ve api_version_unknown koduyla yanıtlanır. GET /v1/versions sürümleri listeler.
Idempotency-Keyheaderstringzorunlu: Her olay için seçtiğiniz ve yeniden denerken tekrar gönderdiğiniz bir değer: UUID gibi 1 ile 255 arası görünür ASCII karakter. Aynı anahtarla yapılan yeniden deneme ilk yanıtı geri alır ve içeriği farklı olsa bile tekrar faturalandırılmaz. Geçerli bir anahtar olmadan istek idempotency_key_required koduyla 400 yanıtı verir.

İstek gövdesi `application/json`

typestringzorunlu

dataWorldPracticeRequestedzorunlu

topicstringzorunlu
source_langstringzorunlu
target_langstringzorunlu
levelintegerzorunlu
tagsarray of stringisteğe bağlı
generateboolean | nullisteğe bağlı

Yanıtlar

202 Olay kaydedildi

idstringzorunlu

typestringzorunlu

created_atstringzorunlu

reactionReactionReport | nullisteğe bağlı

statusReactionStatuszorunlu
plan_idstring | nullisteğe bağlı
plan_statusPlanStatus | nullisteğe bağlı: Olay kabul edildiğinde planın durumu. Yalnızca generating, lesson_plan.ready veya lesson_plan.failed olayının geleceğini vaat eder. Diğer her değer kitaplıktan sunulan bir plandır ve onu şimdi GET /v1/lesson-plans/{id} ile okuyabilirsiniz.
codestring | nullisteğe bağlı
errorstring | nullisteğe bağlı

Hatalar

402application/json: Kullanım başına ücretlendirilen bir istemcinin çağrısı, hiçbir şey harcamadan reddedildi. spend_cap_reached: istemci veya hesabı aylık harcama sınırına ulaştı; sınırı Entegrasyonlar sayfasında yükseltin. metered_billing_inactive: bu hesap için kullanım başına ücretlendirme etkin değil; Entegrasyonlar sayfasında kurun veya ödeme yöntemini güncelleyin.
410application/json: Bu isteğin yanıtlandığı API sürümü sonlandırıldı. Lingara-Version içinde desteklenen bir sürüm gönderin veya istemciyi başka bir sürüme bağlayın.
4XXapplication/json: İstek reddedildi. code nedenini belirtir, error ise bunu sözcüklerle açıklar.
503application/json · text/plain: Hizmet geçici olarak kullanılamıyor; Retry-After içindeki saniye sayısı kadar bekledikten sonra yeniden deneyin. Bakım sırasında gövde, hata zarfı yerine düz metindir.
5XXapplication/json: İstek reddedildi. code nedenini belirtir, error ise bunu sözcüklerle açıklar.

codestringzorunlu: İsteğin neden reddedildiği, dallanmak için kullanılabilecek sabit bir kod olarak: örneğin insufficient_scope (403), rate_limited (429) ve kullanım başına ücretlendirilen bir istemci için spend_cap_reached (402) ile metered_billing_inactive (402).
errorstringzorunlu

Örnek

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ütüphane mi tercih edersiniz? Kütüphaneler bölümüne bakın.