用量与计费
了解插件用量字段、模型用量分组、计费表达式和插件级价格覆盖。
插件报告用量，宿主决定价格
任务插件通过用量钩子报告秒数、数量、token、积分或枚举条件。实际价格、预扣、补扣、结算和退款由 New API 宿主处理。
市场中的用量示例不是官方价格表。 安装插件后仍需在实例的模型价格设置中配置适合自己的价格，并确认渠道和分组规则。
查看用量字段
在插件市场的插件详情中查看「用量字段」。字段定义来自 usageSchema 或当前模型对应的 usageProfiles。
| 类型 | 声明方式 | 用途 |
|---|---|---|
| 数值 | type: "number"，单位为 second、count、token 或 credit | 时长、产物数量、token 或上游计费单位 |
| 布尔值 | type: "boolean" | 是否开启音频等条件 |
| 枚举 | enum: [...] | 分辨率、质量档位或任务类型 |
count 字段可使用 unitLabel 显示「张」「首」等单位名称；它不改变字段 key、单位类型或计费逻辑。字段说明和枚举显示名称也不改变表达式引用的原始值。
为模型配置价格
- 在系统设置的模型价格配置中找到目标模型。
- 查看该模型所使用的插件及用量字段，选择适合的计费模式。
- 使用任务用量价格编辑器，或填写与这些字段匹配的计费表达式。
- 使用插件给出的用量示例检查结果；保存后调用模型，核对实际日志和结算。
例如，只有当插件确实声明并报告 seconds 字段时，下面的示例才有意义：
tier("standard", u("seconds") * 0.02)它表示在 standard 档位中，按 seconds 乘以示例单价计算。0.02 仅用于说明语法，不是任何官方插件的建议价格。原始表达式中的价格使用 USD；最终扣费还受实例的分组与请求倍率等规则影响。
字段必须来自插件
不要把 seconds、duration、video_tokens 等字段视为可互换。表达式中的
u("字段名")
必须与当前插件、当前模型报告的字段一致。任务用量表达式也不能直接照搬文本 token
计费表达式中的所有函数。
按模型区分用量配置
同一个插件可以使用 meta.usageProfiles 为不同模型声明各自的完整 schema 和示例，例如图片模型按张计费、视频模型按秒计费。
- 匹配 profile 的模型使用该 profile 的完整字段定义，不会合并或继承默认
usageSchema。 - 未匹配 profile 的模型使用插件默认 schema 和示例。
- 一个模型最多属于一个 profile；模型名使用
meta.models中的声明名称。 - 更新用量 profile 不会自动迁移已保存的计费表达式。
同一模型的插件级价格覆盖
不同插件可能支持相同模型，却报告不同字段或采用不同成本。模型价格页面可以展示各插件提供方，并分别保存计费表达式。
插件级表达式保存在 billing_setting.plugin_billing_expr，键为 <pluginKey>::<model>。存在覆盖时使用覆盖值，否则继承模型级表达式。没有覆盖的提供方需要与模型表达式兼容。
对于共享模型，若实际表达式中的字面量 u() 字段不在该提供方选中的 schema 中，该提供方会被视为未配置，并返回 model_price_error。应修正模型默认表达式或为该插件配置独立表达式。
保存的覆盖在只剩一个提供方时仍然有效。插件不可用或不再声明模型时，旧覆盖会标记为 stale；它可保持原值或被明确移除，不能当作新的有效绑定。插件级覆盖不会随模型价格同步自动分发。
预扣与完成结算
提交阶段可以提取预计用量，完成阶段再报告实际用量。宿主会根据任务冻结的计费配置计算并处理差额；插件不得返回宿主 quota 或自行执行结算。
用量缺失或解析异常不等于免费。不要把未知用量写成零来掩盖错误；应检查插件日志与宿主记录。合法的显式零值则应保留。
升级时的检查
升级前阅读该版本更新日志的 Migration，重点核对字段更名、计费单位、分辨率档位、默认参数、模型 profile 和提供方覆盖。需要重新配置价格时，应先完成配置再开放流量。
这篇文档对您有帮助吗？
最后更新于