预览、选区与 FPS 导出

先生成视频，再决定如何导出

用 /v1/video-generations 生成视频，保存任务 outputs[] 中的视频资产 ID。用这个 ID 查询元数据、预览和创建导出。改变选区或 FPS 只调用 /v1/animation-exports，无需重新调用生成模型。

GET /v1/assets/{id} 和任务视频输出中的 media 返回实测的 duration_seconds、源平均 fps、解码 frame_count、显示 width、height。无法确认的字段是 null，不使用供应商标称时长或估算帧数替代。平均 FPS 不能代替可变帧率视频的呈现时间戳。

新视频会记录媒体时间轴；旧视频首次预览、FPS 导出或资产查询时按需探测。无法确定实际时长的 FPS 导出会失败，源视频下载仍可用。

预览源素材

向 /v1/assets/{asset_id}/preview 发送：

{
  "timestamps_seconds": [0, 1, 2, 3, 4],
  "max_frame_size": 256
}

时间点必须位于 [0, 实际时长)，允许重复和非顺序输入。返回一张按请求顺序排列、带时间标签的联系表：image 是可刷新的图片资产，width、height 是联系表尺寸；cells[] 包含 index、requested_time_seconds、source_time_seconds 和 rect。矩形使用左上角原点的像素坐标，不包含下方标签。

用 image.download_url 下载图片，不携带 API 或 OAuth 凭据。链接过期后用 image.id 查询资产刷新。预览展示原视频，不做生成、抠图、补帧，也不代表最终 Alpha 质量。

当前预览不扣积分，缓存图片计入账户存储。同一源资产与相同参数会复用仍有效的预览。缓存遵循普通资产保留规则，没有独立的按时间到期策略。

按 FPS 导出

先向 /v1/animation-exports/quote 发送下面的请求，核对费用及 resolved_export；确认后向 /v1/animation-exports 发送相同请求，并提供新的 Idempotency-Key。示例 UUID 需替换为自己的视频资产 ID。

{
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003",
  "selection": {
    "mode": "range",
    "start_seconds": 1,
    "duration_seconds": 2
  },
  "export": {
    "fps": 12,
    "output_formats": ["spritesheet", "spritesheet_json"],
    "output_width": 512,
    "output_height": 512,
    "transparent": {"enabled": true}
  }
}

透明导出仍需先按 alpha_key 流程生成来源，普通视频不能凭此字段自动去背景。不需要透明处理时省略 transparent。

首版 FPS 模式只支持 spritesheet 与 spritesheet_json 的组合；省略格式时自动选择这两个格式。其他组合明确拒绝。旧 frame_count 模式继续支持已有格式。

时间契约

• FPS 是按源视频原速采样的频率，不是播放变速或 AI 补帧。
• 起点 S、时长 T、FPS F 的选区是 [S, S+T)；采样点是 S+i/F，不采终点。
• 帧数为 ceil(T×F)。仅在整数帧边界吸收相对 10^-12 内的十进制序列化误差，不截断 FPS 输入。
• 按实际呈现时间戳选择当时正在显示的源帧。重复采到源帧或目标 FPS 超过源平均帧率时，resolved_export.warnings 提供 SOURCE_FRAMES_REPEATED，不自动插帧。
• 对累计播放边界做正数半入的毫秒取整，再相减生成各帧 duration。1 秒／24 FPS 的帧时长为 41 或 42 ms，总和为 1000 ms。
• 1.1 秒／12 FPS 得到 14 帧，尾帧为 17 ms，总和为 1100 ms。尾段不丢弃，也不均摊到其他帧。
• 如果尾帧量化为 0 ms，返回 TIME_PRECISION_UNSUPPORTED，需要调整选区。
• Aseprite JSON 的逐帧 duration 是播放依据。meta.animgen.fps 始终是目标频率；时长不统一时 frameDurationMs 为 null。

报价与任务共享持久化采样计划；成功任务的 resolved_export 与 Manifest 对应。摘要只包含选区、目标 FPS、帧数、总毫秒数和警告，不在轮询中重复返回全部采样点。

限额、兼容与恢复

默认 FPS 上限为 60、帧数上限为 240，单帧尺寸为 64～1024 像素，选区时长为 0.1～15 秒。图集每边最多 8192 像素、总像素最多 67,108,864。实际配置以 OpenAPI 中的 Schema 和 x-animgen-media-limits 为准。超限报错，不自动降低 FPS。

预览最多 12 个时间点，单帧最长边为 32～512 像素；默认总像素上限 4,194,304、输出上限 10 MiB。媒体探测／预览默认最多同时处理 2 个请求（每个服务进程），媒体处理预算 30 秒，下载每次连接／读取最多 5 秒。源视频最多 256 MiB、120 秒、18,000 个解码帧、单帧 16,777,216 像素。繁忙返回可重试的 MEDIA_BUSY；解码超时返回 MEDIA_TIMEOUT。所有预算均可由服务配置调整。

fps 与 frame_count 互斥；两者均省略仍默认 24 帧。历史任务和 frame_count 请求保留旧采样、默认值与选区容差。新 FPS 请求严格拒绝越界，full 使用实际完整时长，禁止非零起点或额外时长。

一键 /v1/animations 和 MCP generate_animation 仍使用帧数，明确拒绝 FPS。需要 FPS 时使用分阶段流程，从已存在的视频准确计算导出帧数与报价。API 报价不锁价，也不接受 MCP 专用的 quote_id／max_credits。

相同凭据、相同幂等键和相同请求复用同一任务；修改选区／FPS 时使用新键。已失败任务的幂等重试仍返回原失败任务；修正后用新键重新导出，继续复用源资产。取消或失败的导出不会删除源视频。

源视频没有独立的按时间自动到期字段；访问仍受资产／任务删除及账户策略影响，不能视为永久备份。签名 URL 到期不等于资产到期，需要长期保存的素材应下载保管。

MCP 对应流程

1. quote_video_generation → 批准费用 → generate_video → get_video_generation。
2. 保存视频资产 ID，使用 download_asset 查询 media，使用 preview_video 查看候选区间。
3. quote_animation_export → 批准费用 → export_animation → get_animation_export。
4. 下载产物，按 Manifest 逐帧时长导入。

两种创建工具的 quote_id／max_credits 和 idempotency_key 都与 request 同级。报价绑定操作类型；导出报价还绑定源视频、选区与导出参数。取消分别使用 cancel_video_generation 或 cancel_animation_export，参数为 task_id。图片上传沿用现有上传工具。