基础信息
- 站点地址：
https://frameflowvideo.com；站内接口使用同域名下的/api/路径。 - 认证方式：注册并设置密码后登录，浏览器携带
ff_session会话 Cookie。同源fetch使用credentials: 'same-origin'。 - 当前生成方式：一张 JPG / PNG 图片（不超过 10 MB）加可选文字描述；输出固定为 5 秒 / 720p / MP4。
- 额度规则：注册赠送 10 次，创建任务时预扣 1 次，失败自动退回；当前不提供充值或订阅。
本站尚未提供 Bearer Token、第三方 API Key、任务回调或服务端图片编辑接口。裁剪、调节与马赛克在浏览器编辑页完成。
接口一览
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/health | 公开的后端健康与生成配置状态 |
| GET | /api/me | 当前登录账号与 credits 余额 |
| POST | /api/uploads | 上传原图；multipart/form-data，文件字段为 file |
| POST | /api/generations | 提交一次单图生成 |
| GET | /api/generations/{id} | 查询本人的任务状态与结果 |
| GET | /api/generations | 本人的生成历史 |
| GET | /api/files/{id} | 按作品权限播放或读取文件；?download=1 请求下载 |
POST /api/files/:id/export：登录用户导出自己的已完成、审核通过的视频。JSON 参数 format 为 gif 或 mp4，loop 为 none 或 pingpong；MP4 仅接受 pingpong，原 MP4 继续通过文件下载接口获取。支持 10 秒、1080p 以内的作品；GIF 最长边 640px / 15fps，往返 MP4 最长边 1280px / 24fps。成功直接返回文件，不创建生成任务、不扣次数；并发转码返回 429，可稍后重试。取消请求会停止转码。
发起一次生成
- 先登录本站，再向
POST /api/uploads提交原图。上传成功返回 HTTP 201，读取响应中的source_key。 - 向
POST /api/generations发送 JSON，使用上传返回的原图编号，并填写params.prompt。 - 首次创建成功返回 HTTP 202 和
taskId。保留这个编号，用于后续查询。
请求体示例（将 123 换成上传返回的 source_key）：
{
"source_key": "123",
"params": { "prompt": "让云朵缓慢移动，保持主体稳定" }
}时长、分辨率与格式由服务端固定；循环、运动档位、背景选择、参考素材和自定义水印尚未参与生成。服务端只记录实际采用的描述与输出规格。
可发送 Idempotency-Key 请求头防止重复创建；长度 8–128 位，只允许字母、数字和 ._:-。相同账号重试同一个键会返回原任务（HTTP 200），不再次扣额度。
查询任务
使用 GET /api/generations/{taskId} 查询。status 的实际取值为 queued、running、success、fail。成功后 url 指向本站文件接口；失败后 error 提供中文原因，failure 包含原因分类、处理建议及本次额度状态，credits 返回当前余额。
进行中的任务返回 queue：stage 为 queued（本站排队）、provider_queue（生成服务等待）、generating、downloading 或 reviewing。本站排队时 ahead 表示前方任务数，position 从 1 开始；其他阶段这两个值为 null，结束后的 queue 为 null。建议每 3 秒查询一次，不要重复创建任务。关闭页面不会取消任务。
GET /api/generations?limit=8 返回 items、credits 和当前账号最早的未完成任务 active（没有时为 null）。limit 范围 1–100，默认 100；active 不受历史条数限制，可用于刷新后恢复进度。
failure.code 用于区分审核拦截、素材问题、超时或服务异常；展示时使用 message 和 action。credit_status 为 refunded（已退回）、not_charged（未扣除）或 unconfirmed（需联系站长核对），对应说明为 credit_message。进行中与成功任务的 failure 为 null。提交时网络中断不能据此判断是否扣额度，应先查询生成历史，避免重复提交。
轮询可间隔约 3 秒；排队和出片时间以实际任务为准。运行超过 30 分钟仍未完成的任务会按失败处理并退回本站额度。
下载、原图读取和公开作品参数受作者隐私设置与下架状态控制。视频可播放，并不表示访问者一定有下载权限。
错误码
| 状态码 | 典型原因 | 处理方式 |
|---|---|---|
| 400 | INVALID_SOURCE / INVALID_IDEMPOTENCY_KEY | 使用本账号上传的原图，检查幂等键格式 |
| 401 | 登录会话不存在或已过期 | 重新登录本站 |
| 402 | INSUFFICIENT_CREDITS | 测试次数不足，可通过「联系客服」申请追加 |
| 403 | BETA_ENDED 或文件访问权限限制 | 内测到期后停止新生成；登录与本人作品下载保留 |
| 413 | 文件过大 | 通用上传接口上限 20 MB；当前生成原图须不超过 10 MB |
| 415 | UNSUPPORTED_PROVIDER_IMAGE | 生成原图使用 JPG 或 PNG |
| 503 | VIDEO_PROVIDER_NOT_CONFIGURED | 生成通道尚未准备好，请稍后再试 |
与站点功能的一致性
工作台使用上述上传、创建和查询接口，共享账号额度。/api/gen/create 与 /api/gen/query?taskId=... 是兼容入口；内部批量入口在当前最多接受一张原图，多图请求会返回 MULTI_DISABLED。
/api/generations/batch 与 /api/gen/batch 同样支持 Idempotency-Key，并与单任务创建入口共用防重记录。重试同一个操作时须沿用原键；开始新的生成时再换新键。
快速验证
先访问 GET /api/health 检查后端是否响应；登录后访问 GET /api/me 确认会话和余额。这两项检查不会创建生成任务。健康接口中的配置就绪状态不能代替一次完整出片验证。