保存 AI 生成文件：从 PiAPI 输出链接到持久存储
生成任务完成后，应用可以取得结果，但供应商托管的链接并不等于永久媒体库。如果用户以后还需要打开、编辑或下载结果，应将文件复制到你控制的存储，并独立跟踪复制状态。
1. 按实际使用的模型读取输出
查询已保存的任务 ID，确认 data.status 为 completed 后再提取文件。data.output 的结构随模型和任务类型变化。参考对应的任务查询示例，不要假定所有响应都有同一个顶层图片或视频链接。
例如，Kling 文档中的响应包含带有视频资源的 works 数组；其他模型使用不同字段。将任务 ID、模型、任务类型、完成时间及所选资源索引与业务作业一同保存，便于重试时找回同一个结果。
2. 及时复制，逐项核对保留期限
PiAPI 的输出存储文档按服务和托管位置列出不同保留规则。有些条目规定较短期限，有些依供应商 CDN 政策而定；页面也包含历史服务。不要把某个条目的期限推广到所有当前模型，也不要把未说明期限理解为无限保存。
生成完成后，通过Webhook 或轮询流程启动后台复制。在确认回调之前先持久保存作业。下面是一种应用状态顺序；这些存储状态属于你的应用，不是 PiAPI 任务 API 的状态。
generation completed → copy queued → downloading → verified → saved
↘ copy failed → retry copy3. 标记保存之前验证文件内容
从结果链接下载时，不要转发 PiAPI API 密钥。限制允许访问的目标，检查重定向，并设置大小和时间限制。检查 HTTP 状态、实际字节数、预期媒体类型和基本可读性。返回 200 的 HTML 错误页面不是已保存的视频。
先写入临时对象，计算校验和，验证通过后才发布最终对象。使用基于任务 ID 和资源索引的稳定键。记录对象键、字节数、校验和及保存时间，并按你的访问策略提供受控链接。
4. 存储重试与生成重试分开
复制失败时，保留生成已完成的状态，只要源文件仍可用就重试复制。使用持久化唯一记录，防止重复事件创建多条媒体记录。如果链接已不可读，重新查询任务并检查当前输出；这不保证能恢复已过期文件。上线前测试重复事件、下载中断和链接不可用情况。
参考：输出存储、Kling 任务查询和Webhook。这是应用存储方案，不代表 PiAPI 承诺提供归档保存。
