免费网页还是 API？如何选择链接解析方式

由人选择结果时，使用免费网页

偶尔想查看一个公开作品时，可以直接把受支持的链接粘贴到 Clifzo，再查看解析结果。公开网页继续免费，不需要 API 账户，也不会展示 API 积分钱包。

如果你会自行选择格式，又不需要将结果写入其他应用的数据库或队列，网页通常就足够了。无需为了少量链接，额外维护任务持久化、程序密钥和接口调用流程。

结果属于你的产品时，考虑 API

服务端集成能够把解析接到自己的业务记录、任务队列和用户权限中。API 密钥标识第三方账户，账户级限额和积分记录则使客户与管理员能够查看程序使用情况。

API 不会代替产品本身的流程设计。仍需要决定哪些字段有用、多久查询一次任务、来源不可用时如何提示用户。将密钥保存在服务端，并给不同集成创建有名称的独立密钥，便于分别撤销。

一次任务如何变成一条积分记录

成功解析一个作品需要 1 积分，成功获取一页主页列表需要 2 积分。创建任务时从可用积分中预留费用，付费结果成功后结算；失败、取消、到期或没有可用内容时释放预留。

查询余额、流水、任务状态和已有结果不会扣积分，但仍计入账户的请求频率。积分足够，也可能因为正在处理的任务数量而触及并发额度。

• 可用积分：可以用于提交新任务。
• 冻结积分：已由尚未结算的任务预留。
• 同一个已完成任务：重复查看不会再次扣费。

主页不是一次无限展开的请求

一个主页可能有很多作品，因此 API 按页返回，不会在背后无限遍历整个账户。如果结果包含 collection.next_page_url，应用可以在需要时将它提交为一个新任务。

每个成功的主页分页需要 2 积分。请求下一页前应把这个选择展示给用户，并在已有内容足够或来源没有后续页时停止。列表中的作品不会逐条再扣一次积分；单独提交某个作品进行详细解析，才属于另一个 1 积分任务。

区分“恢复原请求”与“创建新任务”

网络超时说明的是客户端看到的现象，并不能证明服务端拒绝了任务。保存 Idempotency-Key 与原始请求体，恢复同一次提交时复用它们，服务端便可以返回或继续原任务，而不再次预留费用。

明确需要一次新的解析时再使用新请求键，例如原结果到期后希望重新取得来源信息。不要仅为了让排队任务“看起来更快”就不断换键重复提交。先阅读 API 文档并验证一个已知来源，再把这些行为接入正式业务。