GloopAPI 接入指南
异步任务与幂等
恢复任务并处理未知提交。
幂等键代表应用的一次业务操作。发送前持久保存请求体、Key 身份与请求键；重放沿用同一键和同一规范化输入。相同键改变请求会冲突，换键会成为新收费操作。
报价与创建
持久图像与视频先读能力目录，再上传或导入输入，获取报价并明确确认创建。图像与视频报价有效 60 秒，工具 报价有效 300 秒；服务端 expires_at 是实际期限。报价不执行任务，也不收费。尚未提交的新调用遇到报价过期或输入/配置变化时重新报价，创建前核对新费用；已经提交但结果未知时不能修改原报价与请求。
图像报价不锁定输入资产，创建时仍会重新核验。视频只允许完整 preset 与当前模式匹配的托管帧。持久视频显式提交 retention: "persistent"，普通视频仍遵守自己的 URL 输入契约。
未知提交的决策
获得任务 ID 后只查询原任务；超时但未获得 ID 时，持久图像与视频按原请求键查询恢复接口。若有原任务记录，继续观察它；若状态为 unknown、submission_unknown、submission_state_unknown、billing_review 或待核对，不把它当作失败或退款，也不能换键重新生成。
工具有 run_id 时用原 Key 查询；创建回包丢失且没有 run_id 时，用原 API Key、原 Idempotency-Key 和原完整请求体重放 POST /v1/tool-runs，保留原 quote_id/version/input/max_cost_usd。已接受运行直接恢复原记录，不依赖新报价或当前开关，也不重复执行任务。历史按 created_at 降序、id 降序排列，next_cursor 必须原样传回；翻页不是快照，游标之前新增的记录需刷新首屏。音频克隆没有相同的按请求键恢复入口，未知提交应保留证据并核查，不能套用图像恢复路径。
三个独立状态
生成成功、账务结清、存储准备完成分别判断。图像可能部分成功，工具可能成功但最终用量未确认，视频可能生成成功但保存失败。后台 worker 继续执行持久任务；浏览器关闭或客户端停止轮询不等于取消。
取消只是请求，可能不支持或来不及阻止成功；继续观察最终状态与账务。存储 retry/archive-retry 只保存原结果，不生成新内容。任务删除需满足终态与最终账务，删除后仍保留幂等和费用证据。
结果获取后先判断存储 ready，再获取文件短时下载地址。临时来源链接过期可能让归档不可恢复；不要用新生成掩盖原任务的保存错误。详见计费与错误处理。