GloopAPI 接入指南
计费
理解预留、结算与文件存储。
模型目录、公开价格摘要与实际调用账务是不同信息。应用应在发起收费操作前核对模型或工具、输入与预算；余额足够也不代表具备调用权限。
预留与结算
请求接受时可能预留估算额度，得到权威用量后按冻结价格结算并补扣或退回差额。实际用量视频报价是估算，不能当作最高支出承诺。工具最大预留由输入边界及冻结规则计算，并在创建时核对费用上限。
status=succeeded 描述执行结果，billing.status=reserved 仍表示费用待确认。最终金额为空也不是零。结果未知的请求或冲突用量保留预留并等待核验；确认失败是否退款由该接口与用量证据决定，不能统一承诺所有失败免费。
同步文本的最终消费看平台用量记录；异步任务查看其账务状态。不要通过再次生成来尝试完成旧任务结算。
工具计价能力
pricing.mode 区分 flat 常量按次、input 按输入预计算和 usage 按最终用量，schema_version 仅表示规则格式。flat 的 amount 是完整常量价，包含零价；input/usage 不提供误导性的常量金额。
pricing.quote_required 决定新调用是否需要报价；requires_usage 表示最终结算是否需要权威用量，包含平台结算约束。即使销售价为 flat，仍可能需要报价和最终用量；按这两个能力字段决策。requires_usage=true 必须提交覆盖 maximum_usd 的 max_cost_usd，成功后等待权威用量再结算。input 且无需最终用量的规则报价后即可按输入金额结算，不等待最终用量。
metered_pricing 仅限制需要最终用量的新调用，不限制无需最终用量的常量/输入规则，也不阻断已接受运行查询、原请求幂等重放或冻结账务恢复。报价绑定 Key、工具版本、规范输入与价格/来源配置。常量工具提供 quote_id 时也始终核验报价。目录展示的最低档位不代表工具免费。
文件保留与空间
普通 API 归档文件按部署的保留天数到期，持久图像/视频使用引用保护长期保留，expires_at=0 表示不定时过期。存储占用与生成收费分别计算；ready 之前不保证能下载。
删除持久任务会清空结果并解除可删除引用，后台清理未共享文件；共享引用与账务、幂等记录保留。删除文件或保存失败不自动退回已产生的生成费用。重试保存申请可用空间并复用原结果，不再次生成。
额度不足
403、402 或配额错误应先检查账户与 Key 限额。持久鉴权允许有效耗尽 Key 读取历史，但新任务仍需要预算。需要结算原任务时继续查询原记录；不要换 Key 或请求键重提。见鉴权和异步任务与幂等。