企业官网建设流程全解析

从静态图到无缝循环：sprite-gen Grok 视频管线完整教程

【免费下载链接】sprite-genGenerate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.项目地址: https://gitcode.com/gh_mirrors/sp/sprite-gen

sprite-gen是一条「一张静态图进、游戏可用精灵出」的自动化管线。它的Grok 视频管线（Pipeline B）会把任意一张角色立绘交给Grok Imagine 视频模型生成动画片段，再自动完成色度键抠像、无缝循环检测与裁剪，最终产出透明 GIF / WebP / 帧条（strip）——每一帧都带真实 alpha，可直接放进游戏引擎播放，无需手动找剪切点。本教程带你从零走完这条管线。

上面这张图里的狼、骑士和史莱姆，每一个都只从一张静态图开始：Grok Imagine 负责让它动起来，sprite-gen 负责提取出干净的透明循环。

一、为什么需要「视频管线」而不是「精灵表」？

直接让图像模型画「sprite sheet」，你通常会得到：每帧脸都变、背景抠不掉、姿势漂移出格的 PNG。sprite-gen 给出两条独立管线：

Pipeline B 的核心思想是：让视频模型当动画师，让 sprite-gen 当剪辑师。整条链长这样：

静态图 ──video-canvas──▶ 画布 ──video──▶ clip.mp4 ──video-frames──▶ 透明帧 ──video-loop──▶ strip · GIF · WebP

四个阶段分别由sprite_gen/video/canvas.py、sprite_gen/gen/video.py、sprite_gen/video/frames.py、sprite_gen/video/loop.py实现，docs/video-pipeline.md 是这条管线的完整契约文档。

二、一键安装与凭证配置

git clone https://gitcode.com/gh_mirrors/sp/sprite-gen cd sprite-gen python3 -m venv .venv && source .venv/bin/activate pip install -e . sprite-gen --help

依赖方面还需要两个二进制：ffmpeg（抽帧）和img2webp（带精确 alpha 的 WebP）。如果你希望行走/奔跑循环拥有「跳帧修复 + 多方向周期对齐」，建议执行一次sprite-gen rife install安装 RIFE 光流插值。

Grok 凭证二选一（详见 docs/video.md）：

• grok login订阅登录（默认，优先）：装好grokCLI 后执行grok login，消耗你 SuperGrok 的 Imagine 配额，不产生 console 计费；
• XAI_API_KEY：export XAI_API_KEY=xai-…，按 xAI console 信用计费。

注意：只要存在可用的登录态，订阅登录永远优先；token 过期时工具会明确告诉你如何刷新（在空目录运行grok models），而不会在上传中途给你一个 403。

三、video-canvas：给动作留足空间

视频模型会保留输入图的构图，所以「跳跃时头发出框」这种问题不能靠提示词解决，只能靠给静态图补白边解决。video-canvas内置了一张状态画布表：

画布还有一个隐藏功劳：它把背景重新涂成精确的色度键色（#00FF00绿或洋红）。图像模型每次画的「绿色」都略有偏差，视频模型又会忠实复制这个偏差——video-canvas会用抠图引擎的 alpha 蒙版把背景重涂成纯键色，保证后面抽帧时每一帧都能干净擦除。角落颜色不是平整单色的图会被直接拒收：不平整的背景无法被安全地扩展。

四、video：Grok Imagine 让静态图动起来

sprite-gen video一次调用 = 一张静态图（+提示词）→ 一个经过校验的 mp4：

sprite-gen video --image canvas.png \ --prompt "Camera locked. Walks naturally in place, as if on a treadmill, without moving across the screen." \ --out clip.mp4 --duration 3

这条管线对提示词做了大量「实测调优」（docs/video-pipeline.md 记录了每条句式在多少个角色上测过多少遍）：

• 行走/奔跑：统一写成「原地自然行走，如同在跑步机上，不要横穿画面」——实测 2.16.0 的句式让正面行走 2/2 保持朝向；
• 攻击：不是一段循环，而是一次定时打击——起手（约 0.5s）→ 挥击（约 0.25s）→ 保持击中姿势（约 0.3s）→ 回到起始站姿（约 0.5s）。video-set会自动用--last-frame把片段钉在首帧上，保证打出去必须收回来；
• 待机：双脚钉死，只允许呼吸、发丝与布料微动、一次眨眼，并且明确点名「不要原地踏步」。

五、video-frames：逐帧抠成透明

mp4 到手后，video-frames用ffmpeg抽出每一帧，并逐帧走和静态图导入完全相同的cutout色度键引擎：

几个关键机制，让视频抠图比想象中可靠得多：

1. 按模型实际画出的键色抠图：Grok 会把#FF00FF画成 (216, 46, 147) 之类的「脏洋红」。引擎逐帧检测边框的主导颜色，同时以纯键色和实际画出的颜色为中心擦除，不再出现「同一帧半抠半留」。
2. 溢色修正（--spill auto）：视频模型会把键色画进角色身上（金属上的绿色光泽）。引擎用「生成这段视频所用的那张静态图」做参照——如果静态图本身不含键色材质，就启用完整溢色去除；如果角色本来就是绿色的，则保守处理，保住本体颜色。
3. 边缘接触检查：任何不透明像素出现在画面四边 4px 内即判失败，并按颜色分类告诉你原因——是键色残留（去重做画布），还是主体被构图裁切（去加大画布）。

这张武士拔刀循环就是「一张静态图 → Grok 片段 → 抽帧 → 自动剪切」的直接产物：没有人工指定剪切点。

六、video-loop：无缝循环如何被「量」出来

这是整条管线的灵魂。为什么 AI 片段不能直接循环？因为图像转视频模型画的是连续不重复的运动——最后一帧几乎永远不是第一帧，朴素循环回跳时人眼会捕捉到「跳变（pop）」。「交叉淡化」看得见淡入淡出，「乒乓反转」有一半时间在倒放，都被明确否决。

video-loop的做法是先找真实周期，再选接缝：

1. 在缩略帧上构建距离矩阵，读取全局周期曲线P[L] = 平均 |f[j] − f[j+L]|；
2. 取最接近最深处且在其 15% 以内的最小局部极小值——真实重复会在 2×、3× 周期处再次下陷，而「半周期相似帧」（双腿互换的错觉）下陷明显更浅，这就是「1.5 倍周期陷阱」的解法；
3. 周期确定后才为它挑选起点：接缝距离除以循环内部平均相邻距离，并在切口两侧各取四分之一周期做邻域一致性检查，偏爱「连贯的重复区域」而非碰巧端点相似。

行走/奔跑还有专属的时间窗口（按秒计，因为步频是身体的事实，与片段长短无关）：walk 0.5–1.6s，run 0.3–1.2s。若半周期候选同样可信，报告会标记review_recommended = true，提醒你肉眼确认（评审清单见 docs/loop-review.md）。

循环的输出是三种文件：<name>.strip.png帧条 +.strip.json（引擎可直接用）、透明 GIF、带精确 alpha 的 WebP，外加一份机器可读报告。

七、video-set：一次生成整套动作

单状态走通后，video-set会把「画布 → 视频 → 抽帧 → 循环」四步批量跑完所有（方向 × 状态）组合：

sprite-gen video-set --base side=still.png --base front=front.png \ --states idle,walk,run,jump,attack --out-dir set/

它替你处理的琐事：

• 限流与重试：xAI 配额为 2 请求/秒，启动自动错峰（--start-gap 2），429 有 15s/30s 的有界重试；
• 统一角色尺寸：不同状态用不同形状画布，像素高度天然不一致；--body-height N让整套循环保持同一站立身高；
• 幂等重跑：已有片段的条目直接复用，不加--force不浪费配额；单条目失败只影响它自己，错误写进table.md；
• 多方向周期对齐：正面/侧面/背面各切出的行走循环，会被重采样到整套的中位周期长度（缺的帧由 RIFE 光流插值补齐），并统一旋转到「同一只脚落地」的相位——这样游戏引擎切换朝向时步频完全一致。

八、交付前看一眼：评审与排查

自动门禁建立的是「周期正确、接缝干净、alpha 完好」这类数值事实；它不能替你判断「左右腿是否真的交替」「步态是否可信」。发布前建议：

1. 把生成的 GIF 以源帧率连播至少三遍，观察循环点有无停顿、跳帧或反向；
2. 看报告里的cycle.review_recommended、suspects与warnings——半周期嫌疑、RIFE 插值融化帧、无法辨认脚步的循环都会显式列出；
3. 常见失败排查（键色残留、构图裁切、步态漂移）见 docs/troubleshooting.md 与 docs/loop-repair.md。

总结：一张图，一整组动作

如果你想继续深入，从这几个入口开始：视频→循环管线契约 docs/video-pipeline.md、Grok 视频引擎 docs/video.md、循环修复 docs/loop-repair.md、总文档索引 docs/README.md，以及核心实现目录 sprite_gen/video/ 与 sprite_gen/gen/video.py。

【免费下载链接】sprite-genGenerate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.项目地址: https://gitcode.com/gh_mirrors/sp/sprite-gen