发送事件

参数

Lingara-Versionheaderstring可选

回应此请求所用的 API 版本。不提供时，访问令牌使用其客户端绑定的版本，不带令牌的请求使用当前版本。仍在开发中的版本只能通过在此指定来访问。未知版本会以 400 回应，代码为 api_version_unknown。GET /v1/versions 会列出所有版本。

Idempotency-Keyheaderstring必填

你为每个事件选定、重试时原样再发的值：1 到 255 个可见 ASCII 字符，例如 UUID。使用同一个键重试会拿回第一次的应答，且不会再次计费，即使请求内容不同。没有有效的键时，请求以 400 和代码 idempotency_key_required 应答。

请求体 application/json

typestring必填

dataWorldPracticeRequested必填

topicstring必填

source_langstring必填

target_langstring必填

levelinteger必填

tagsarray of string可选

generateboolean | null可选

响应

202 事件已记录

idstring必填

typestring必填

created_atstring必填

reactionReactionReport | null可选

statusReactionStatus必填

plan_idstring | null可选

plan_statusPlanStatus | null可选

事件被接受时计划的状态。只有 generating 保证随后会有 lesson_plan.ready 或 lesson_plan.failed。其他任何值都是由资料库提供的计划，现在就可以用 GET /v1/lesson-plans/{id} 读取。

codestring | null可选

errorstring | null可选

错误

402application/json

一个按用量计费的客户端的调用在产生任何花费之前就被拒绝了。spend_cap_reached：客户端或其账户已达到每月支出上限；请在集成页面提高上限。metered_billing_inactive：此账户的按用量计费未激活；请在集成页面进行设置，或更新付款方式。

410application/json

回应此请求所用的 API 版本已停用。请在 Lingara-Version 中发送一个受支持的版本，或将客户端绑定到其他版本。

4XXapplication/json

请求被拒绝。code 说明原因，error 用文字描述原因。

503application/json · text/plain

服务暂时不可用；请在 Retry-After 所示的秒数之后重试。维护期间，响应体为纯文本，而不是错误信封。

5XXapplication/json

请求被拒绝。code 说明原因，error 用文字描述原因。

codestring必填

请求被拒绝的原因，以稳定的代码表示，可据此进行分支处理：例如 insufficient_scope（403）、rate_limited（429），以及按用量计费的客户端的 spend_cap_reached（402）和 metered_billing_inactive（402）。

errorstring必填

示例

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

更喜欢用库？请参阅“库”部分。