如何避免AI生成费白花：ClipForge付费安全机制实战——dryRun预览、付费前守门与任务恢复

ClipForge 是一款开源的 AI 带货短视频神器：上传一张商品图，它会自动提炼卖点、写种草脚本，并调用云端大模型生成画面与配音，一键产出抖音、快手、小红书、TikTok Shop 的卖货视频。但云端视频模型按秒计费，一次误操作（模型选错、重复提交、断网丢任务）就可能白烧真金白银。ClipForge 用一套完整的付费安全机制来解决这个问题：dryRun 免费预览、付费前守门校验、两阶段提交与任务恢复，让你每一分生成费都花在明处。

一、为什么 AI 生成费容易白花？

在 ClipForge 早期（issue #16），一次"图生视频"点击引发了四个真实缺陷叠加：

ClipForge 的修复思路可以概括为一句话：在花钱之前能挡的，绝不留到花钱之后；钱已经花了的，任务 ID 绝不能丢。

二、dryRun 预览：先免费报价，再决定是否付费

以"九宫格一键整片"（storyboard-film）为例，接口同时支持两种模式（见 src/app/api/project/[id]/storyboard-film/route.ts）：

• dryRun: true（免费预览）：不提交任何生成请求、不花费一分钱，返回——
  • 将实际被计费的模型（与付费提交走同一套解析逻辑，保证"预览什么就收什么费"）；
  • 完整提示词、分镜数、总秒数、参考图数量与配额检查；
  • 基于平台公开目录价的费用预估（含分辨率加价倍数，取上限值，而非低价下限）；
  • 对白密度告警等建议性提示。
• 正式提交：只有你确认后才走真正的付费路径。

💡 关键点：预览和正式提交解析出的是同一个计费模型。平台不公布价格的模型，预估字段为undefined，界面会诚实显示"未知"，而不是假装"免费"。

三、单次花费上限（spendCap）：给你的钱包装一道硬闸

在设置页可以配置"单次花费上限"（默认 $5，见 src/app/settings/page.tsx）。正式提交时，服务端会在扣费前做花费守门：

预估上限（estimate.maxUsd） > 上限（spendCapUsd） 且 未显式确认 → 直接拒绝（400），费用为零

拦截信息会告诉你"预估最高 $X 超过你的上限 $Y"，并给出四个选项：调高上限、调低分辨率、换更便宜的模型、或缩短脚本（源码见 route.ts 花费守门段）。只有用户在确认卡片上明确点了"仍要生成"（acknowledgeOverCap: true），才会放行——而且确认卡片上显示的正是刚刚 dryRun 报价的那个数字，所见即所扣。

四、付费前守门：请求发出前的三层校验

真正的"守门"发生在 atlas-cloud.ts 的resolveVideoModel：任何能力不匹配都会在提交前抛错，一分钱不花。

1. 模式匹配校验：你带了首帧图想"图生视频"，但配置的是文生视频模型？自动改写为同家族的 image-to-video 变体（如seedance-2.0/text-to-video→.../image-to-video）；若没有对应变体，报错MODEL_MODE_MISMATCH并停止。
2. 素材完整性校验：图生视频模式却拿不到首帧图？抛MISSING_FIRST_FRAME，绝不"将就提交一个与你的图无关的视频"。
3. 重试策略守门：创建任务的 POST 是非幂等请求。base.ts 的重试规则 规定：只有服务端明确拒绝（HTTP 429，保证未受理）才允许重试；超时或 5xx 时绝不自动重试（因为服务器可能已受理），并提示"服务端可能已受理"，防止重复计费。

这些规则并非"口说无凭"，而是有完整的回归测试网兜底：paid-task-safety.test.ts 逐条覆盖了重试次数（POST 只发 1 次 / GET 可重试 3 次）、模型改写、缺素材拒提、轮询容错等场景。

五、两阶段提交 + 任务恢复：断网也拿不走的付费任务

钱花出去之后，ClipForge 的核心原则是：任务 ID 必须在轮询之前落库。

两阶段提交（submitVideoTask）：

1. 阶段一：提交——submitVideoTask只发请求、不等待，拿到云端任务 ID 立即返回；
2. 落库——路由层立刻调用recordAiTask把 taskId 写入本地ai_tasks表（src/lib/ai-tasks.ts）；
3. 阶段二：等待——waitForTask开始轮询状态。

轮询容错：状态查询偶尔失败（超时、断网）不会中断等待，连续失败数次后自动恢复；只有持续失败才报STATUS_UNKNOWN（而不是"任务失败"），并且错误里携带 taskId——因为"状态未知 ≠ 已完成扣费"，钱很可能已经花了。

任务恢复 UI：素材页顶部会出现蓝色"待处理任务"卡片（assets/page.tsx 恢复卡片），列出所有"已提交但结果未取回"的任务，提供**"恢复"按钮：只查询并继续等待该任务的结果，而不是重新提交**（重新提交 = 再扣一次费）。任务中心读取状态时同样不会重新提交生成请求，详见 docs/task-recovery.md。

六、三步上手：把你的生成费管起来

1. 设置花费上限：打开设置页 → 生成参数 → "单次花费上限"，按你的预算填入（默认 $5）。
2. 先预览再提交：在脚本页或素材页点击"预览"（dryRun），确认展示的是你预期的计费模型与费用上限值。
3. 遇到"状态未知"不要慌：不要点重新生成，直接点恢复卡片里的"恢复"按钮，让 ClipForge 用已保存的任务 ID 取回结果。

总结

ClipForge 的付费安全机制把"AI 生成费白花"的四大风险逐层堵死：

配合 0 成本批量出片与本地自部署，这套机制让"0 预算误伤"成为默认行为——生成费只为你确认过的、看得懂的报价买单。