# Product Motion Gif

> 把一张产品图/场景图/人像图变成可循环的动图。原理是让 GPT-Image 2.5 一次性生成 4x4 多格帧图，再切帧、修循环缝、按节奏合成 GIF/WebP/MP4。四类动效：A 相机环绕（默认「左→右 60°」）、B 相机锁死+角色自己做动作（可无参考图从零画游戏人物招式）、C 相机锁死+背景后掠的速度型动作、D 机位锁死+只变表情（人像表情包）。触发词：产品动图、产品 GIF、环绕动图、旋转动图、多格图、frame sheet、turntable gif、product animation、动作 GIF、游戏人物 GIF、角色动图、表情包、表情 GIF、夸张表情、让图动起来。

- Skill: `liangdabiao/product-motion-gif` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx get-skill add liangdabiao/product-motion-gif`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liangdabiao/product-motion-gif/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liangdabiao (https://skillmd.com/u/liangdabiao)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liangdabiao/product-motion-gif

---


# product-motion-gif

产品图/场景图 → 可循环动图。核心是 GPT-Image 2.5 的一致性：**一次生成 4x4=16 帧多格图**，
再切帧合成。不要一帧一次生成——那样漂移严重且贵。

## 什么时候用

- 用户给产品图或场景图，要"动起来"的展示素材（环绕、旋转、悬浮）。
- 用户**不给参考图**，只说"生成一个 XX 在做 XX 的动图"（角色招式 / 游戏人物动作）——
  `apiz_image.py` 的 `--ref` 是可选的，**纯文本生成也支持**（见下"四类动效"）。
- 用户给**人像/人脸图**，要做"表情包"（同一个人做一整套夸张表情，如"周星驰那种夸张"）
  —— 用 D 类模板 `prompts/face-expression-loop-4x4.txt`，参见"四类动效"。
- 输出目标：微信/详情页可用的 GIF、现代平台用的 WebP、投放用的 MP4。

**不适合**：多主体互动、复杂剧情动作、刁钻运镜、需要 48 帧以上的长动画。

## 四类动效，别抄错对方的写法

| | A. 相机绕场景（orbit 系列） | B. 相机锁死、角色做动作（`char-action-fixed-4x4.txt`） | C. 相机锁死、背景后掠、角色做动作（`char-action-scroll`，**待固化**） | D. 机位锁死、只变表情（`face-expression-loop-4x4.txt`） |
|---|---|---|---|---|
| 参考图 | 必须给 | **不用给**，从零画 | **不用给**，从零画 | **必须给**——脸就是身份 |
| 相机 | 绕主体扫 60° | **完全不动**（no orbit / zoom / dolly / pan） | **完全不动** | **完全不动，且锁得最死** |
| 背景 | **必须横移**——转动的唯一线索（硬规则 17） | **纹丝不动** | **必须向后掠**——速度感的唯一来源（近快远慢视差） | 纹丝不动（纯黑底最稳） |
| 主体 | 居中不动，转动由背景承载 | 居中，**动作全在它身上** | 居中，动作在它身上，**它不横穿画面** | 一张脸（头肩），居中等大，**只有面部肌肉在变** |
| 循环 | `--loop pingpong`（硬规则 3） | `--loop cycle`，cell 16 收回起手式闭环 | `--loop cycle`，整圈动作（如空翻 360°）首尾同姿 | `--loop cycle`，cell 16 收回 cell 1 的中性脸 |
| 适用 | 产品/场景展示 | 招式、技能、站立动作 | 飞行、奔跑、冲刺这类**有速度**的动作 | 表情包、面部情绪演出 |

**A 的"背景必须横移"照抄进 B 会把平涂底搅花**；**B 的"背景纹丝不动"照抄进 C 就没有速度感**；
**C 的"背景后掠"照抄进 A 会让环绕读成推轨**；**把 B/C 的全身动作写法抄进 D 会让脸在画面里乱跑。**

D 类三条专属写法（照抄自模板，别删）：

1. **机位锁得比 B/C 更死。** 脸对**平移**的敏感度远高于全身——全身横移 1% 看不出来，
   脸横移 1% 就已经像在点头晃脑。所以模板里那句 *"nothing in the picture changes except the
   expression on it"* 是核心约束。
2. **允许点名"节拍"，但接缝要写成过渡。** 硬规则 5 禁止分段描述是针对**连续量**（角度、位移）
   的；**表情是离散状态**（中性 / 坏笑 / 震惊 / 大笑），本来就该分节拍。写法：节拍只落在
   具体格号的 ANCHORS 上（cell 1 / 5 / 9 / 12 / 16），并加一句
   *"the face never snaps instantly from one extreme to another"*。
3. **所有不对称特征必须显式给方位，且统一用观众视角。** 只写 "a crooked smile" 不写左右，
   模型会**逐格随机镜像**，观感就是脸在抖。用 `the corner of the mouth on the viewer's left`，
   不要用 `his left`（模型常算反）。

D 类首个实例：**m1.jpg 低多边形人像做夸张表情包**（中性→挑眉坏笑→瞪眼震惊→咧嘴大笑→回中性），
2K / 3:4（单格 384×512）/ Flare，prompt 5305 字符 → `D:/image25/gif-lab/out/face-expr/`。
**尚未经用户验收**，暂不并入硬规则。

C 类提示语要点：把"角速度"写成可数的整数步（如 `15 equal steps of 24 degrees` = 整圈 360°），
并明写"背景每格后掠相同的量、近处比远处走得远"；同时保留 B 类的身份锁与人口线。

C 类首个实例：**孙行者翻筋斗云飞速前进**（任天堂 3D 卡通渲染 + 蓝天绿丘后掠 + 完整前空翻），
prompt 5975 字符 → `D:/image25/gif-lab/out/monkeyking/`。**尚未经用户验收**。



稳定性最好的区间是「**纯色 / 影棚背景 + 单主体 + 简单动作**」。**平涂底的全出血插画**
（整幅就是纯色底、没有道具，如 k1）实测主体一致性同样很好、可以放心用——难点不在画得像不像，
而在**转动读不读得出来**：背景没东西可横移时只能靠主体剪影承载，必须按硬规则 17 把
"该变的部件"逐个写清。真正的雷区是**背景杂乱 + 多主体**：越界会随机抖动、画面漂移，
甚至出现生物/物理准确性错误。

## 前置条件

- `apiz` CLI 已安装并登录（`apiz auth status`）。模型见下"模型选择"。
- Python 需 `Pillow`、`numpy`；MP4 需要 `ffmpeg`。
- Windows 上若 `bash` 报 `head/ls: command not found`，先补 PATH：
  `export PATH="/c/Windows/System32:/c/Windows:/c/Users/49707/.workbuddy/binaries/PortableGit/versions/1.2.0/usr/bin:$PATH"`

## 模型选择（省钱技巧）

| 模型 | 用途 | 实测成本（high/2K） |
|---|---|---|
| `apiz/gpt-image-2.5-flare` | **试 prompt 阶段默认用这个** | 16:9 → 39 points；4:3 → 53 points |
| `apiz/gpt-image-2.5-sunburst` | 定稿出正式版 | 约为 Flare 的 2 倍（16:9 → 78 points） |

两者参数完全相同，改 `--model` 即可切换。**试错一律走 Flare。**

### 尺寸档位：默认 2K；用户要"更清晰/4K"时才上 4K

**默认一律 `--size 2K`。** 用户明确说"不清晰""来个 4K"时才用 `--size 4K`
（那是授权花钱，否则算擅自重跑——见「验收」一节）。

要分清两件事，别只记住"4K 是假的"：

**一、4K 不是原生 4K 生成。** 实测（Flare / high / 4:3 / 4K）元数据：

```
"upstream_width": 2048, "upstream_height": 1536    ← 上游其实只生成 2K
"target_width":   3264, "target_height":   2448    ← 放大 1.59 倍交差
"scale": 1.5938
"price": 133                                        ← 2K 是 53
```

**二、在"固定输出尺寸"下比锐度，4K 白花钱。** 同一素材、同样输出 640×480：

| 素材来源 | 拉普拉斯锐度 | 高频能量占比 |
|---|---|---|
| 2K → 640 | 22.35 | 51.4% |
| 4K → 640 | 23.08（+3.3%） | 52.9% |

差异在噪声量级，肉眼不可辨。

**三、但 4K 真正的价值是"可用的原生输出上限"——这才是它该用的场合：**

| 生成尺寸 | 单格像素 | 能原生输出的长边 |
|---|---|---|
| 2K | 384×512（4:3） | 512，**拉到 640 已经在放大 1.25 倍，发软** |
| 4K | 612×816（4:3） | **816，零放大** |

→ **成品长边 ≤ 512px**：用 2K，省 2.5 倍钱。
→ **成品长边要做到 800px 左右**：2K 在物理上供给不了像素，**必须用 4K**
  （j1 的 816×594 原生版就是这么来的；i1 用户说"不清晰"的根因也是这个，
  不是合成参数问题）。
→ 想再大只能改网格（3×3 → 2K 下单格 682px），代价是帧数变少、流畅度下降。
→ 跨版本比清晰度用 `scripts/compare_clear.py`（同格归一化到同一显示尺寸 + 2x 局部放大），
  别凭感觉说"更清晰了"。

## 透明底 + 像素风：五条链路硬约束（已实测）

这一节的每一条都是踩出来的，不是猜的。

**一、透明底走 `--transparency`，返回的是 PNG。**
`apiz_image.py --transparency` → `params.transparency = true`，实测返回 `content_type: image/png`，
带 alpha 通道。`make_gif.py --bg transparent` 配合使用（`--bg auto` 也会自动识别出 alpha）。

**二、模型给的 alpha 是"柔边"的，而 GIF 只有 1-bit 透明。**
实测一张透明底像素图：alpha 有 **255 种取值**，`alpha == 0` 占 **50.7%**，
其余从 1 连续过渡到 254，**没有任何一个像素是 255**。
`giflab.quantize_frames` 用 `> 128` 阈值二值化，后果是：
- 轮廓上 1–2px 的羽化被切掉或补上 → 边缘变硬（像素画正合要求，无害）；
- **"半透明残影 / 柔光拖尾"会被阈值化成实心色块**，观感是脏污而不是残影。
→ 要干净的残影/拖尾，**必须在 prompt 里要求"用实心像素画残影，不许半透明"**。
→ **WebP 支持真 alpha，是透明素材的正确载体，必须同时交付 WebP。**

**三、像素风必须 `--resample nearest --no-dither`。**
默认 LANCZOS 会把硬边糊掉；Floyd 抖动会在平色区撒噪点，并在透明轮廓上造出成片半透明像素。
两个开关都是为像素风加的（`resize_all(resample=...)` / `quantize_frames(dither=...)`）。

**四、`--size` 只能取"源单格长边"或它的整数分之一，否则像素块大小不均匀。**
`resize_all` 按"长边 = `--size`"等比缩放。**用 NEAREST 做非整数倍缩放 = 像素块一大一小**
（1px、2px、1px、2px…），这是像素画最显眼的硬伤。
→ 2K 4:3 单格是 512×384，所以 `--size` 用 **512（不缩放）** 或 **128（精确 1/4）**。
→ **坑**：`--trim union` 会**改变**帧尺寸（实测 512×384 裁成 **460×384**），
  此时按 512 输出等于 NEAREST **放大 1.11 倍**，正好踩中上一条。
  **像素风请用 `--trim none`**（顺带白送一个好处：16 格画框完全一致，对游戏素材是加分项），
  或先看日志 `global crop ... -> WxH` 再定 `--size`。

**五、透明底 + WebP(method=6) 很慢，别用前台跑；失败先查真实原因。**
- 透明 512px × 16 帧导出 WebP 实测 **> 3 分钟**，前台默认 120s 超时会把它 SIGTERM 掉，
  且**输出走管道是块缓冲的，日志全丢**——现象是"exit 1 / SIGTERM / 无任何输出"。
  → 长任务一律 `run_in_background`；`python -u` 关缓冲看实时日志。
- 透明素材**跳过 MP4**（`--no-mp4`）：`export_mp4` 把帧合成到白底，透明信息本就不存在。
- apiz 生成失败时**别猜**：`apiz tasks get <task-id>` 能拿到 `result.error`。
  实测一次失败的真实原因是
  `Your request did not meet content safety guidelines. Your tokens have been credited back`
  ——疑似被 `run-and-gun`（含 "gun"）触发，改成 `action platformer` 后同一份 prompt 一次通过。
  **内容安全被拒不扣 points（已退回）**，可以直接改词重试。

## 标准流程

```bash
SK="D:/image25/.workbuddy/skills/product-motion-gif"
PY="C:/Users/49707/.workbuddy/binaries/python/versions/3.13.12/python.exe"

# 1. 参考图入库，拿公网 URL（apiz 只吃 URL，不吃本地路径）
apiz upload ./product.jpg --folder myproj
#    -> https://cdn-hk.51sux.com/storage/myproj/....jpg
#    外链图可直接转存：apiz transfer "<url>"

# 2. 生成 4x4 多格图（prompt 用 prompts/ 下的模板，按主体改前两段）
#    默认模板 prompts/orbit60-l2r-4x4.txt = 左 30° → 右 30°（见硬规则 1）
#    画幅跟随原图：方形→1:1，4:3→4:3，16:9→16:9，竖构图（如 1024×1598）→2:3
#    默认 --size 2K；只有用户要求"更清晰/4K"时才改 4K（见「尺寸档位」）
#    ⚠ 整份 prompt 必须 ≤6000 字符：实测 6449 可用、9213 被接口拒收
#      （HTTP 400 "prompt 必填且长度为 1-4000 字符"）。
#      注释/变更记录写进同名 .notes.md，不要混在 prompt 文件里；
#      apiz_image.py 会自动截掉单独成行 "---" 之后的全部内容（TO OPERATOR / CHANGE LOG）。
#      它会打印 "[apiz_image] prompt chars: N"，超限直接本地报错，不浪费请求。
"$PY" "$SK/scripts/apiz_image.py" \
  --ref "<上一步的 URL>" \
  --prompt-file "$SK/prompts/orbit60-l2r-4x4.txt" \
  --out out/sheet.json --model apiz/gpt-image-2.5-flare \
  --quality high --size 2K --ratio 4:3

# 3. 切帧编号 → 立刻给人看多格图（不能省、不能拖，也别忘了给人"怎么看"）
"$PY" "$SK/scripts/contact_sheet.py" out/sheet.jpg out/contact.png 4 4 480
"$PY" "$SK/scripts/ab_frames.py" out/sheet.jpg out/ab-01-16.png 1 16 4 4 620
"$PY" "$SK/scripts/motion_smooth.py" out/sheet.jpg 4 4      # 量化数字，仅作参考

# 4. 切帧 + 合成
"$PY" "$SK/scripts/make_gif.py" --sheet out/sheet.jpg --outdir out/run1 \
  --rows 4 --cols 4 --canvas tight --bg auto --loop pingpong \
  --keep-frames --quality-report out/run1/qa.json
```

产物：`animation.gif`、`animation.webp`、`animation.mp4`，加 `frames/` 和 `qa.json`。
（`--size 640 --timing ramp --duration 70 --ramp 2.6,0.7,1.8 --max-kb 3000` 都已是默认值，
不用重复写。）

## 硬规则

**前两条是已验收的效果标准，改动前先问用户。**

1. **展示类环绕默认「左 → 右 60°」，不要 180°、也不要用 90°。（已验收）**
   准确指：**cell 1 = 参考视角左 30°、cell 8 = 正好是参考视角、cell 16 = 参考视角右 30°**，
   相机从左往右扫过 60°，**参考视角落在整张表的正中间**。
   模板：`prompts/orbit60-l2r-4x4.txt`（默认）。

   验收历程：180° 太大（依次看到正面→侧面→背面，那是"转圈圈"不是"产品展示"）→
   90° 仍偏大 → 60° 通过 → **方向从"单向 0°→60°"改成"左 30°→右 30°"后转角明显更好读**
   （j1 实测花树/瀑布/木船相对峰体大幅换位，比此前各版都明显），故定为默认。

   prompt 里必须写死这一句，否则模型会把 cell 1 当成参考视角、整段扫描偏 30°：
   `Do not start the sheet at the reference viewpoint - cell 8 is the reference viewpoint.`

   注："环绕"指**相机绕场景转**，不是模型自转（要明写 "it is the CAMERA that orbits"）；
   边界仍是**不越过正侧面、绝不露背面**。要右→左扫就镜像 LEFT/RIGHT 与锚点描述。

2. **合成默认用"前慢后快"节奏（`--timing ramp`，已是默认）。**
   用户要求：**开头慢、逐渐加快**，让观众看清起始画面。
   默认形状 `--ramp 2.6,0.7,1.8` + `--duration 70`，实测 30 帧停留时长：
   `180×6 → 170×4 → 160×2 → 150×3 ... → 70×2 → 60×2`，总约 4.0 秒。
   `--timing even` 是备选（按每格实际变化量分配时间，追求恒定速度感时才用）。

3. **旋转/环绕类必须 `--loop pingpong`。**
   16 帧只覆盖单程角度，正向播完再镜像回退才无缝（共 30 帧）。用 `auto` 会退化成
   `cycle`，接缝处硬跳。原因：旋转被判为 `pose-change`，而 `halfloop` 只在
   `kind == "translation"` 时生效，`loopcut` 找不到匹配姿态。

4. **默认不要逐帧稳像（`--stabilize off`，已是默认值）。**
   这是最容易踩的坑：逐帧稳像给每一帧算一个**不同**的位移量，"漂移估计误差"直接变成
   帧间抖动。实测一张真实环绕图：pose jitter 指数 **1.87（原始）→ 2.22（开稳像）→
   1.88（关掉）**。它非但没让画面更稳，反而制造了抖动。
   注意：环绕时主体本来就会横向位移，**这是真实视差，不要拿稳像去抹平它**。
   只需要整体重新居中时用 `--stabilize anchor`——一次性常量偏移，帧间关系完全保留。

5. **prompt 里禁止分阶段描述镜头，要用"线性插值 + 每格增量相同"。**
   写成"第 1–4 格近景、第 5–11 格后拉、第 12–16 格全景"，模型就会在阶段交界处猛变
   （实测第 3→4 格明显跳变）。正确写法是把 16 格定义成**一次连续运动的 16 个等时间采样**：
   "cell 1 是起点，cell 16 是终点，中间的每一格恰好落在同一条线性插值的等比位置上；
   任意相邻两格之间的变化量完全相同；全程没有加速、停顿、快段或慢段"。

6. **prompt 必须写明"是相机在环绕，不是模型在自转"，并用数字封顶。**
   否则模型会去转模型本身，几何会崩。同时钉死：固定距离/高度/焦距、地平线不漂、
   全程恰好 N 度、分成等步、**每格主体完整不出格**、场景内每个物体的形状位置颜色不变、
   纯色无缝背景、无文字水印边框。
   量化封顶比定性描述有效得多，例如：`apparent size changes by less than 5%`、
   `max 8% horizontal travel`。

7. **稳像若真的开启，填充色必须是不透明画布色，否则出黑边。**
   `shift_frame` 默认 `fill=(255,255,255,255)`。若填透明 `(0,0,0,0)`，
   后续 `convert("RGB")` 会把透明像素压成**纯黑**——这就是 GIF 边缘那道黑边。
   只有真正的透明底素材才传 `(0,0,0,0)`。
   同理 `quantize_frames` / `export_webp` 走 `flatten_rgb()` 合成到画布色，不要直接 convert。

8. **只做 4x4 / 16 帧；GIF 体积上限 3MB。**
   帧数越多漂移和抖动越明显，成本还翻倍。体积上用户明确 **3MB 可接受**
   （`--max-kb 3000`）。超出预算时阶梯会先降尺寸再降色数，**最低不要跌破 460px/96 色**
   （那个档位明显发糊）；宁可放宽预算，也不要用糊的档位交付。
   注意 2K 生成 + 4x4 时单格只有 512px，所以 640px 是放大得来的；细节密集的素材
   在 3MB 内通常只能保住 **544px** 左右，交付时把实际尺寸说清楚。
9. **多张参考图时，在 prompt 里写清每张的职责。** 实测「外观图 + 剖面图」一起喂时，
   模型会默认把**剖面图也画进画面**。必须显式分工：
   `Image 1 (exterior) is the MAIN VIEW` / `Image 2 (cutaway) is the STRUCTURE REFERENCE
   ONLY - do NOT draw the cutaway, do NOT open up the walls`。
10. **"锁构图"会直接抹掉旋转——大主体/全出血素材必须放开。（已验收）**
    环绕之所以"看起来在转"，靠的是**背景视差**（近处划过、远处慢移）+
    **主体相对画面自然移动**。prompt 里写 `every cell shows the whole subject, complete and
    uncropped` / `consistent margins` / `背景元素形状位置固定`，等于把仅有的两条旋转线索封死 ——
    模型会走最安全路径：**几乎照抄原图 + 微小抖动**，观感是"抖/呼吸"而不是"转"。

    实测（同素材、同模型、同角度，只改这三条写法，g1.jpg）：

    | 写法 | motion 判定 | area_cv | 15 步总变化量 |
    |---|---|---|---|
    | 锁构图（主体不出格 + 背景不动） | `translation` | 1.3% | 2.225 |
    | **放开（漂移 + 视差 + 角度锚点）** | **`pose-change`** | **5.1%** | **3.315** |

    放开写法三件套（模板见 `prompts/orbit60-drift-4x4.txt`）：
    1. **要求主体在画格里漂移**，允许跑出画格边界，明写"不许逐格重新居中、不许保持边距不变"。
       ⚠️ **这一条后来被用户改掉了**：默认应改为**主体居中、由背景横移体现转动**
       （硬规则 17）——因为"相机始终瞄准主体"本身就和"主体必须漂移"冲突。
       只有**主体大到居中会让画面呆住**时才回退到漂移版。
    2. **要求背景视差**，明写"背景元素不许钉死在原位置"；
    3. **给三个具体视觉锚点**：cell 1 = 参考图原视角、cell 8 ≈ 28°（哪一侧开始转出视线）、
       cell 16 = 60°（哪一侧转到画面中央、谁进入画面、谁被遮住）。
    再加一句**失败判据**：`A sheet in which the subject is in the same orientation in every
    cell is a FAILED sheet.`

    **适用边界（重要）**：主体小、居中、四周有留白的静物摆件（乐高摆件那类）**可以继续锁构图**，
    60° 已经验证有效；**主体大 / 全出血插画 / 特写构图**则必须放开，否则转不动。
    代价是**姿态一致性下降**（马腿、披风形状会漂）——这是取舍，不是 bug。
11. **复合运动（环绕 + 推近/拉远）时，QA 的 `area_cv` 阈值是误报。**
    `area_cv > 12%` 会触发 `verdict: REVIEW / silhouette area varies 47.9% - subject may be
    reshaping`。但**只要 prompt 里刻意要求了 dolly，面积大幅变化就是设计要求**，不是缺陷。
    实测 i1.jpg（60° 环绕 + 推近 30%）：`area_cv = 49.4%` → QA 报 REVIEW，
    而检查表上"由远到近"正是用户想要的效果。
    → 遇到 dolly 时**不看 `area_cv` 的绝对值，改看它是否单调增长**（不允许中途缩回去）。
    → 同理，prompt 里"apparent size < 5%"这条封顶**必须删掉并改成**"面积匀速单调增长约 N%"，
      否则和 dolly 直接冲突。
    → 复合运动的代价：帧间步长容易忽大忽小（i1 实测 `0.213 0.335 0.276 0.303 0.335 0.336
      0.768 0.767 0.188 0.330 0.296 0.652 0.606 0.593 0.144`，step_cv 1.175），
      比单一环绕（step_cv 0.446~0.7）差。**追求平顺就做单一运动，追求冲击力才叠复合运动。**
12. **素材形态决定交付格式和体积档位——插画类必须放宽或改走 WebP。**
    实测同参数下 GIF 的表现差异极大：

    | 素材 | 默认 3MB 预算 | 放开后 | WebP 同帧 |
    |---|---|---|---|
    | 纯色背景静物（i1 乐高山峰） | 480×640 / 255 色 / 3.8MB | 同左（已到上限） | **651KB 满分辨率** |
    | 全出血插画（g1 武将） | **345×460 / 96 色 / 2.9MB（发糊档）** | 408×544 / 192 色 / 4.7MB | **1576KB 满分辨率** |

    原因：GIF 调色板对**大面积平坦色块**很省（纯色背景素材 3MB 就能给到 480×640），
    对**全出血画作**极不划算（没有平坦区，3MB 直接把画面打到 345px/96 色，
    就是硬规则 8 里标"明显发糊、不要交付"的那一档）。
    → **静物/纯色背景**：GIF 3MB 够用，照常交付。
    → **全出血插画/照片**：`--max-kb 6000` 起步，并**必须同时交付 WebP**——
      WebP 满分辨率只要 GIF 的 1/3 体积，是这类素材的正确载体，GIF 只留作兼容。
13. **参考图自带水印时，必须在 prompt 里显式禁止复现。**
    实测有效（g1 武将右下角小红书水印、h1 骑士右下角小红书水印，两版都清干净）：
    在 REFERENCE 段说明"参考图带水印"，并在 OUTPUT 段写
    `do NOT reproduce it, and do not reproduce any other logo, handle or overlaid image`。
    只写笼统的 `no watermarks` 不够——要把它点名到"参考图右下角那一个"。
14. **主体自身带强运动趋势时，转向会被抵消。（待验证）**
    实测 h1.jpg（马朝左下方奔驰奔跑）用同一套 v2 写法，只拿到
    `translation / area_cv 1.5% / 总变化 1.755`，明显弱于 g1（静止昂扬姿态，
    `pose-change / 5.1% / 3.315`）。推测模型把"相机绕行"与"主体奔行"混在一起，
    两个运动互相抵消。**样本数 1，尚未定论**；遇到"主体正在飞奔/冲刺"的素材时，
    预期转向会打折，可考虑改用"推近"这类不依赖旋转的动效（见硬规则 11）。
15. **场景内角色动作（"镜头之外还有个东西要动一下"）要单开一段，并配双失败判据。（已验收）**
    用户可以在环绕之外要求"画面里的某个角色动一下"（j1.jpg：猴子沿山脊走路）。写法：

    - 单开一段 `THE <ROLE> - the only moving thing in the whole scene`，写清四件事：
      **动作方式**（如"四条腿交替、一组前摆另一组支撑、尾巴轻摆、头保持平视朝行进方向"）、
      **总位移**（如"全程约 1.5 倍身长"）、**匀速不停**、**保持同一比例与颜色**；
      再列出**禁止项**（不跳、不爬、不站起、不转身、不跑、不变大变小、不换位置、不出画、
      不消失、不许出现第二只）。
    - 其余段落改成 `WHAT MUST NOT CHANGE - everything EXCEPT the <role>`：所有道具/建筑/
      液体锁死（瀑布不流、船不漂不摇、水面不荡）。
    - **失败判据从一条扩成两条**：①16 格视角相同 = 失败；②16 格角色姿态相同 = 失败。
    - **验证方法**：整格对比看不出小角色动没动，必须用 `scripts/cell_zoom.py` 把同一区域
      跨格放大并排看（j1 实测猴子从山脊左端走到右峰下，一眼可见）。
    - 一个能自证方向的现象：**相机往右转会让画面内容向左移**，如果小角色在画面里往
      **相反方向**移动，就证明是它自己走的，不是被镜头带过去的。

16. **提示语必须先指名"绕的是谁"（`SUBJECT` 段），且整份 prompt ≤6000 字符。**
    - **不指名主体，模型就不知道角度绕哪个轴量**，容易退化成平移或原地微动。
      默认模板已加 `SUBJECT - the pivot the camera circles` 段，且必须放在
      `REFERENCE` 之前（先指名，再描述）。三个模板（旧版）此前全无此段，
      只在相机行里以 "the scene / the subject" 抽象带过——**这是被用户点出来的真实缺口**。
    - **长度上限**：实测 **6449 字符可用、9213 字符被接口拒收**，报
      `HTTP 400 … prompt 必填且长度为 1—4000 字符`。
      → **整份 prompt 控制在 6000 字符以内。**
      → 注释 / 变更记录 / 操作说明**写进同名 `.notes.md`**，不要混进 prompt 文件。
      → `scripts/apiz_image.py` 已加两道保护：单独成行的 `---` 之后全部截断
        （TO OPERATOR / CHANGE LOG 不再发给模型）；超限直接本地报错，
        并打印 `[apiz_image] prompt chars: N`。

17. **主体居中、由背景横移体现转动（已验收）。**（用户决定，替换旧的"主体必须漂移"写法）
    `always aimed at the subject` 与 `the subject must DRIFT … may run off the frame edge`
    **互相冲突**：始终瞄准轴心的相机，会把主体稳在画面中部，**由背景横移体现转动**。
    所以 prompt 里写的是：主体保持在画面中部、不逐格重新构图、不左右滑动、不变尺寸。

    - **背景是平涂无特征场时**（纯色底、暗色底、无道具，如 k1 的青色场）：没有东西可横移 →
      **转动只能由主体剪影承载**。必须**逐个写出**"该变的地方"（哪一侧躯干朝前、腰带结与
      侧缝落点、近侧肩膀遮住多少、飘带投射到画面哪一处），并写上一句
      **"a frozen pose seen from a new angle is not the same picture"**。
      **只写一句 "silhouette must change" 不够**——k1 验收版正是把 3–5 处逐项列出才成立的。
    - 模板 `prompts/orbit60-l2r-4x4.txt` 的 `SUBJECT` 段与
      `HOW TO MAKE THE ORBIT VISIBLE` 第 2 条已按此重写，含金句与占位提示，**不要改回去**；
      填写要点见 `orbit60-l2r-4x4.notes.md`。
    - 反例（重要）：对同一素材，**"主体必须漂移、可以跑出画格"**的旧写法（k1 第一版）
      被用户否决（"很小的动，根本没有旋转"）；**改成主体居中之后才通过**。

## 验收（最重要的一条）

**质检数据只是参考，不是标准；出图了就要尽快给用户自己看。** 流程必须是：


1. **出图即交付，不要拖。** 多格图生成完 → **立刻**跑 `contact_sheet.py` 出带帧号检查表；
   合成完 → **立刻**把 GIF / WebP 交给用户。**不要为了"先自己判一遍"而延后交付**，
   也不要拿量化数字当结论。
2. **QA / `motion_smooth` 等一切量化数字只作参考**，用途是提示"哪里可能有问题"
   （比如某一步跳变、边缘不干净），**不能用来判定效果好坏**：
   `area_cv`、`pose` 在轮廓近似的宽扁场景上会失灵（见「判读 QA 报告」最后一条），
   数字说"平移"而肉眼明明在转的情况真实发生过。
3. **人是唯一验收标准，AI 自查不算数。** 用户看了一眼说"行"，才算过。
4. **不要在用户验收前就把"经验"写进本文件**——没验收的优化是瞎优化。
5. **交付时带上"怎么看"**：给首尾帧对比图（`ab_frames.py`）、动作特写（`cell_zoom.py`），
   让用户一眼能判断，而不是丢一个 GIF 让他自己猜。
6. **交付时不写效果判断。** 不要写"这次转得很明显""效果比上一版好"这类结论——用户明确
   批评过 AI 乱下判断。可以说的只有**中性事实**（帧数、尺寸、体积、某格有跳变这类客观观察）
   和**中性的"怎么看"**（哪张对比图看哪两格）。**尤其不要把 QA 的判定转述给用户**：
   `pose-change` / `translation` 在这类素材上会整体反报（见「判读 QA 报告」的 k1 反例）。
7. **重新生成多格图（花 points 的调用）必须先经用户同意**；用户主动说"来个 4K / 重跑"
   即视为授权。本地合成（切帧、合成、导出）不花钱，可以直接做。

## 判读 QA 报告

> **先记住：这一节的数字全部只是参考，不是结论。** 用它们找"哪里可能有问题"，
> 效果好不好由用户看图和 GIF 判。数字与肉眼冲突时，**以肉眼为准**。

```jsonc
{
  "motion": {"kind": "pose-change", "area_cv": 0.06},  // 环绕=pose-change
  "loop": "pingpong",
  "border": {"mean_rgb": [139.5, 208.9, 253.0], "near_black_fraction": 0.0},
  "output": {"timing": "ramp", "dwell_ms": [180, 180, ...]},
  "verdict": "PASS | REVIEW"
}
```

- **黑边只认 `near_black_fraction`（接近纯黑的像素占比），不要用亮度判定。**
  稳像填充透明的特征是 RGBA→RGB 压成 `(0,0,0)`，真实主体/阴影/彩色背景**三个通道
  不会同时全黑**。之前的版本按"外圈亮度 < 235"判暗带，遇到**蓝色影棚背景**（RGB 约
  `140,209,253`，亮度天然只有 200）会 100% 误报，也会把"主体故意出画"误判成黑边。
  判定：`near_black_fraction > 2%` 才算真黑边。`mean_rgb` 是给人看的，用来确认外圈
  是不是背景色本身。
  **例外（已实测）**：素材背景本身就是纯黑时（如 m1 人像表情包，背景是刻意的纯黑底），
  `near_black_fraction` 会报到 **93.7%** 并给出 `verdict: REVIEW` +
  `pure-black band on the canvas border ... the stabiliser filled with transparent`——
  这是**预期值，不是黑边**（该条判据默认"外圈非黑才算正常"，黑底素材天然违反它）。
  此时改看两点确认：`darkest_channel` ≈ 0 且 `mean_rgb` 就是设定背景色 → 忽略该 issue。
  **注意 `--bg auto` 也会报同一类误判**：`auto` 从四角采样背景色，剪影式深色头发容易把
  采样带偏、主体框跟着飘。**背景是纯黑/纯色时直接写死 `--bg 0,0,0`（或对应 RGB），不要用 auto。**
- `area_cv` 超过 12% → 主体在"变形"而不只是"移动"，多半是多主体或复杂动作。
  （60° 环绕实测 **6%** 左右；180° 全环绕会到 50%+，属正常。）
  **例外**：prompt 里刻意要求 dolly（推近/拉远）时，`area_cv` 大是设计要求，不是缺陷
  —— 见硬规则 11，此时改看面积是否**单调**变化。
- **"到底转没转"——四步判定，顺序不要乱：**
  1. `motion.kind`：`translation` = 只有平移没有换角度；`pose-change` = 真的换了姿态/视角。
     环绕类**通常**应当拿到 `pose-change`。**但它会误报，不要当铁证。**
  2. **先看步长序列的形态，再看总量。** `pose step per frame` 如果是**高低交替**
     （`0.117 0.166 0.082 0.168 0.077...`），说明在**原地来回摆**，观感是抖不是转；
     应该是**平稳推进**（缓慢递减、末段收一下也算正常）。
  3. **总量只作辅助参考，绝不能单独下结论。** 实测 g1 同素材同角度：锁构图写法
     `translation / 1.3% / 总变化 2.225` → 放开写法 `pose-change / 5.1% / 3.315`。
     但 k1 给出了完全相反的结果（下一条），**总量大 ≠ 转得好**——摆动同样能把总量堆大。
  4. 最后用 `scripts/ab_frames.py` 把 cell 1 和 cell 16 并排放大看一眼确认。
- **k1 反例：QA 的结论可能与人工验收完全相反——一切以肉眼为准。**
  同一素材（全出血平涂底单主体）先后两版：

  | 版本 | QA `kind` | pose 总量 | 步长形态 | 用户结论 |
  |---|---|---|---|---|
  | 第一版 | **`pose-change`** | 3.81（更大） | 高低交替 `0.098 0.095 0.195 0.190 0.230 0.423 0.199 0.449…` | **否决**（"很小的动，根本没有旋转"） |
  | 验收版 | **`translation`** | 1.53（更小） | 平稳 `0.236 0.151 0.060 0.119 0.088 0.051 0.036 0.138 0.106 0.057 0.050 0.062 0.049 0.062 0.270` | **通过** |

  原因：这两个指标测的是**整幅轮廓**。平涂背景的单主体素材，剪影在 16 格里高度相似，
  于是"原地来回摆"被判成 `pose-change`、"真正绕轴扫过"被判成 `translation`——**判定整体反了**。
  同类还有 j1：QA 报 `translation / area_cv 2.8%`，而宽扁景观 + 纯白背景从任何角度看轮廓
  都差不多，内部结构（瀑布、花树、木船）其实已经大幅换位。
  → 结论：**平涂底 / 全出血 / 宽扁轮廓近似 这三类素材，`kind`、`area_cv`、pose 总量全部不可用**，
  只能靠 `scripts/ab_frames.py`（首尾帧）+ `scripts/cell_zoom.py`（局部）+ 人眼判。
  交付时**不要**把 QA 结论说给用户听（会误导），只给图和 GIF。
- `dwell_ms` 在 ramp 模式下应当**单调递减**；若成片顶在下限 60ms，说明收尾偏慢。
- 判断"抖"来自模型还是合成：`motion_smooth.py` 跑**多格图**得 `jitter_idx`（模型的责任），
  再跑**合成后的 frames/** 得另一个值。后者明显更高 = 合成环节在恶化，先查 `--stabilize`。
- **输出尺寸会被体积预算反推。** `--max-kb` 是硬预算：阶梯会从 `--size` 起逐级降尺寸、
  再降色数，直到塞进预算。所以 3MB 预算下不一定能拿到 640px —— 细节密集的素材
  （樱花树、砖墙纹理）压缩率低，可能落到 544px。**日志里 `gif ... (WxH ...)` 报的是实际
  落地尺寸**，要以它为准（曾有个 bug 把尺寸静默压回源单格宽度，导致 GIF 比同帧的 WebP 还小）。

## 文件

- `scripts/apiz_image.py` — apiz CLI 包装，生成多格图并落 JSON（`--model` 可切 flare/sunburst）。
- `scripts/giflab.py` — 库：切帧、遮罩、稳像（含 anchor）、节奏曲线（`even_durations` /
  `ramp_durations`）、循环修复、调色板、导出。
- `scripts/make_gif.py` — CLI：多格图进，GIF/WebP/MP4/QA 出。
- `scripts/contact_sheet.py` — 把多格图切成**带帧号的检查表**，交给用户逐帧验收。
- `scripts/motion_smooth.py` — 量化帧间均匀度（`jitter_idx`）。
- `scripts/verify_edges.py` — 按播放器合成方式量 GIF 边缘，验证黑边是否清净。
- `scripts/ab_frames.py` — **抽任意两帧并排 2x 放大**，用来肉眼确认"到底转没转"
  （判定流程第 4 步；`python ab_frames.py sheet.jpg out.png 1 16 4 4 460`）。
- `scripts/cell_zoom.py` — **跨格放大同一小块区域并排**，用来确认场景里的**小角色/小物件
  是否真的动了**（整格对比看不出来的，它一眼就能看）。见硬规则 15。
  用法：`python cell_zoom.py sheet.jpg out.png "1,5,9,13,16" 0.40,0.12,1.0,0.55 4 4 2.2 monkey`
  （第 4 个参数是**格内相对坐标** x0,y0,x1,y1，取值 0–1）。
- `scripts/compare_clear.py` — **跨版本清晰度对照**：把两张多格图的同一格归一化到
  同一显示尺寸并排，再叠加 2x 局部放大。比"2K vs 4K"这类差异靠它，别凭感觉。
  `python compare_clear.py A.jpg B.jpg out.png 16 4 4 816 "2K->640" "4K->816"`。
- `prompts/char-action-fixed-4x4.txt` — **无参考图 / 单角色动作**模板（B 类）：相机锁死、
  角色自己完成一套连续动作、特效为唯一可变元素。含 `CHARACTER` / `LOOK` / `THE ACTION` /
  `CAMERA - LOCKED` / `WHAT MUST NOT CHANGE` / `FAILURE` 段与 `<<< >>>` 占位。
  **本体 5800 字符**（贴近 6000 上限，填充后必须复测）。填写要点与防坑清单在
  `char-action-fixed-4x4.notes.md`。**首个实例：唐僧 + 九环锡杖聚气挥出金光**，
  4:3 / 2K / Flare，prompt 5204 字符 → `D:/image25/gif-lab/out/tangmonk/`。
  **效果尚未经用户验收**，暂不并入硬规则。
- `prompts/char-action-fixed-4x4.notes.md` — 上者的填写说明（怎么指名角色、道具怎么当刚体
  写、动作为什么要写成"一条弧 + 三锚点"、为什么用 `cycle` 而不是 `pingpong`）。不进 prompt。
- `prompts/face-expression-loop-4x4.txt` — **有参考图 / 机位锁死 / 只变表情**模板（D 类）：
  头肩特写，用于表情包。含 `SUBJECT` / `CAMERA - LOCKED` / `LOOK` / `THE EXPRESSION ARC`
  （5 个 ANCHORS）/ `WHAT MAY CHANGE / WHAT MUST NOT` / `FAILURE` 段与 `<<< >>>` 占位。
  **本体 5917 字符**（贴近 6000 上限，填充后必须复测）。填写要点在
  `face-expression-loop-4x4.notes.md`。**首个实例：m1.jpg 夸张表情包**，
  3:4 / 2K / Flare，prompt 5305 字符 → `D:/image25/gif-lab/out/face-expr/`。
  **效果尚未经用户验收**，暂不并入硬规则。
- `prompts/face-expression-loop-4x4.notes.md` — 上者的填写说明：四类动效对照、
  为什么 D 类机位要锁得最死、为什么 D 类**允许**分节拍（与硬规则 5 的关系）、
  左右方位为什么必须用 `viewer's left`、以及两个必须记住的坑
  （**`--trim` 必须用 `none`**、**黑底用 `--bg 0,0,0` 不要用 `auto`**）。不进 prompt。
- `prompts/orbit60-l2r-4x4.txt` — **默认模板**：**左 30° → 右 30°**（60° 相机环绕，
  参考视角在表中间），见硬规则 1。含 `SUBJECT` 段（硬规则 16）、
  `HOW TO MAKE THE ORBIT VISIBLE` 四条（硬规则 10 / 17）、动作段（硬规则 15）的
  `<<< >>>` 占位，共 9 组。**模板本体 5886 字符**（限 6000，见硬规则 16）。
  **填写要点与操作说明在 `orbit60-l2r-4x4.notes.md`**（不进 prompt）。
- `prompts/orbit60-4x4.txt` — 旧默认：单向 0° → 60° 相机环绕（**历史版本**，
  转角不如"左→右"好读，除特殊需要否则用 l2r 那版）。
- `prompts/orbit60-drift-4x4.txt` — **主体漂移版（历史版本，别默认用）**：60° 环绕 + 放开
  构图锁（主体漂移 + 背景视差 + 角度锚点）。硬规则 10 的实测对照就是它跑出来的（g1 已验收）。
  用户后续已把默认改成**主体居中、背景横移**（硬规则 17），**默认请用 l2r 那版**；
  仅当"主体极大、居中会让画面呆住"时才回退到它。文件末尾有 `---` 之后的操作说明。
- `prompts/orbit60-dollyin-4x4.txt` — **复合运动**：60° 环绕 + 由远到近推近约 30%，
  见硬规则 11。注意它**没有**"尺度变化 <5%"封顶，改成"面积匀速单调增长"。
- `prompts/orbit60-two-ref-4x4.txt` — 双参考图版（外观主视角 + 结构参考），见硬规则 9。
- `prompts/turntable-180-4x4.txt` — 180° 环绕（单主体产品，历史版本）。
- `prompts/orbit-reveal-180-16x9.txt` — 宽幅场景 180° 环绕 + 后拉揭示，16:9（历史版本）。
- `README.md` — **面向非技术使用者的白话说明**（无命令、无参数），第二节是**五类效果的
  案例集**（A 环绕 / B 角色动作 / C 速度型 / C2 像素透明 / D 表情包），每类一张真实成品的
  GIF + "你会提供什么 / 你可以这么说 / 适合什么"。用户是要"发给朋友/同事看"的场合，
  给这份，不要给 SKILL.md。
- `cases/` — README 案例集用的**成品动图**（约 7.5MB，纯展示用，不是素材）：
  `A-orbit-60-l2r.gif`（218×320/30 帧，原 `README-demo.gif`）、
  `B-character-action.gif`（640×480，唐僧锡杖聚气）、
  `C-scroll-flight.gif`（640×480，孙行者翻筋斗云）、
  `C2-arcade-transparent.gif` + `.webp`（512×384，街机像素透明底，webp 是真 alpha 版）、
  `C2-arcade-pixel128.gif`（128×96 老街机颗粒）、
  `D-expression-loop.gif`（180×240 表情包）。
  **新增案例就往这里放并同步 README 第二节的表格**；A 类那张就是早期的 `README-demo.gif`，
  不要在原位置重复放一份。

