计费与点数
API 版本 2026-10-virile-dragon
两种付费方式
客户端有两种计费方式，其模式在创建时就已固定。allowance 客户端消耗其所有者的套餐额度，与你的应用是同一份额度，从不从银行卡扣费。metered 客户端不消耗额度：它的每次调用都消耗点数，从你按用量计费订阅绑定的银行卡扣费。应用代表其他用户、使用通过授权码获得的令牌发起的调用，无论客户端采用哪种模式，始终消耗该用户的额度。
每次调用的点数
metered 客户端的一次调用消耗其权限范围对应的点数，见下表；对应 0 点的权限范围不收费。GET /v1/usage 报告的 units 按这些权重换算为点数。无论客户端固定在哪个版本，调用都按发起当天生效的权重计费：旧版本参考文档中的表格记录的是该版本发布时的权重，而不是一次调用今天的费用。
vocab:generate | 生成词汇表。 | 生成词汇表 |
lesson_plans:read | 读取你的课程计划并重新连接到其进度。 | 获取课程计划重新连接到课程计划 |
lesson_plans:write | 创建课程计划。 | 创建课程计划 |
tutor:converse | 与辅导老师对话。需要付费套餐。 | 发送一轮辅导对话 |
usage:read | 查看你的剩余额度，或 `metered` 客户端本月的用量。 | 获取剩余额度 |
events:read | 读取与你的账户相关的事件，并注册接收这些事件的端点。 | 列出事件事件流 |
events:write | 从你的游戏或集成向 Lingara 发送事件。 | 发送事件 |
embed:mint | 为你的游戏或网站的玩家签发短期令牌，并删除玩家。仅限按用量计费的客户端。 | 为玩家签发令牌删除玩家解除玩家与其 Lingara 账户的关联 |
embed:play | 代表玩家行事：发送其练习结果，并与其进行 NPC 对话。 | 将玩家关联到其 Lingara 账户向 NPC 发送一句话 |
价格
每个点数 US$0.004。用量按月计费，每个自然月从 1 日（UTC）开始计算，从你按用量计费订阅绑定的银行卡扣费。
支出上限
你的账户有一个以点数计的每月上限，每个 metered 客户端还可以设置自己更低的上限；两者都在集成页面上设置。一旦客户端或你的账户达到上限，该客户端的调用会被拒绝，返回 402 和代码 spend_cap_reached，直到下个月开始或上限被提高。
按用量计费未激活时
按用量计费未激活时，metered 客户端的调用会被拒绝，返回 402 和代码 metered_billing_inactive：包括设置之前、付款逾期期间以及取消之后。请在集成页面（地址为 app.getlingara.com/admin）上设置、管理或取消按用量计费。管理会打开 Stripe 的账单门户，你可以在其中更换银行卡并查看发票。
如译文与英文参考文档不一致，以英文参考文档为准。