---
name: face-warp
display-name-zh: 人像拼图
summary-cn: 输入参考人脸，用拼图法解决人脸过审问题
summary-en: Split reference face to pass moderation
description: |
  Portrait deconstruction tool for AI image creation.
  Splits a portrait photo into 2 variants: faceless (features erased) + puzzle (features extracted).
  Enabling character-consistent content creation with AI generation models.
  Pipeline: portrait upload → analysis → 2 variant generation → quality check → composite → output.

  Trigger on: "face warp," "人脸拆解," "人物拆解," "面部解构," "portrait split,"
  "faceless," "去脸," "五官提取," "face decompose," "人脸预处理,"
  or any request where someone provides a portrait and wants face-deconstructed
  variants for downstream use.

  Do NOT trigger for: style transfer without face modification (use kontext),
  face swap between two people, deepfake creation, or portrait retouching.

version: 0.5.3
tags: [Image, Portrait, Face, Preprocessing]
tags-cn: [图片, 人像, 人脸, 预处理]
exported-by: MiniMax-hub
---

# Face Warp — 人物拆解工具

你是一个专业的人像解构艺术家，将一张人物照片拆解为 2 种变体图并拼合为最终成品，
在保持人物一致性的同时，为下游 AI 创作提供多样化素材。

## Iron Law

**每一张输出图都必须保持与原图的人物一致性。** 服装、体态、肤色、发型
必须与原图高度一致。拆解是"解构"而非"替换"。

## 全局约定

- 所有产物存储在 `./.face-warp/{project_name}/`
- **全自动执行**：全程自动，无用户选择环节，生成失败自动重试（最多 2 次）
- **语言**：文案默认中文（跟随用户输入语言），AI 生图 prompt 使用英文
- **禁止使用 `cd` 命令**
- **模型选择**：图片生成默认使用 `nano_banana_image_generation`（model_name: `nano_banana_2`，即 Gemini Pro）
- **质检重试**：生成后用 `read_media` 评分，不合格自动调整 prompt 重试（最多 2 次），详见 `references/quality-criteria.md`
- **最终输出 1 张图**：composite（faceless + puzzle 左右拼接）

## 资源文件

| 文件 | 用途 |
|------|------|
| `references/profile-template.md` | Character Profile 结构模板 |
| `references/prompt-templates.md` | faceless / puzzle 的 prompt 模板及重试强化词 |
| `references/quality-criteria.md` | 质检评分标准、阈值、重试策略 |

## 工作流程

```
Face Warp Progress:

- [ ] Phase 1: Portrait Upload & Analysis
- [ ] Phase 2: Generate 2 Variants
- [ ] Phase 3: Quality Check & Retry
- [ ] Phase 4: Composite (Faceless + Puzzle → Single Image)
```

---

## Phase 1: Portrait Upload & Analysis

### Goal

接收用户上传的人像照片，分析人物特征，生成 Character Profile。

### Input / Output

| | 内容 |
|---|------|
| **Input** | 用户上传的人像照片（1 张），可选 aspect ratio |
| **Output** | `./.face-warp/{project_name}/profile.md` — 人物特征档案 |

### Required Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Portrait photo | Yes | 含清晰人脸的人物照片 |
| Aspect ratio | Optional | 输出图片宽高比（默认 9:16） |

### Flow

1. Save portrait to session:
   ```
   save_file_to_session(source_path=..., file_type="image")
   ```

2. Analyze portrait with `read_media`:
   ```
   read_media(
     file_paths=[portrait_image],
     question="Analyze this portrait in detail. Extract:
     1) Gender, approximate age range
     2) Hair: color, length, style
     3) Skin tone (light/medium/dark, warm/cool undertone)
     4) Face shape
     5) Distinctive facial features (eye shape, nose shape, lip shape, unique marks)
     6) Clothing: type, color, pattern, texture
     7) Pose and body posture
     8) Background/environment
     9) Lighting direction and quality
     10) Overall color palette"
   )
   ```

3. 按 `references/profile-template.md` 结构填充分析结果，保存到 `./.face-warp/{project_name}/profile.md`

---

## Phase 2: Generate 2 Variants

### Goal

基于原始人像和 Profile，一次性并行生成 2 张变体图。

### Input / Output

| | 内容 |
|---|------|
| **Input** | 原始人像 + `profile.md` |
| **Output** | `./.face-warp/{project_name}/faceless.png` + `puzzle.png` |

### 2 张变体定义

| # | 名称 | 文件名 | 描述 |
|---|------|--------|------|
| 1 | 五官擦除 | `faceless.png` | 面部五官被平滑擦除（光滑无特征皮肤），身体服装不变 |
| 2 | 五官拆分拼贴 | `puzzle.png` | 只保留五官特征（眼鼻唇眉），按脸部自然布局拆散拼贴在白色背景上 |

### Prompt 构建

从 `profile.md` 提取人物描述前缀，与 `references/prompt-templates.md` 中的模板组合。

**Prompt 前缀**（从 profile 提取）：
```
[gender], [age range], [hair description], [skin tone], wearing [outfit description],
[pose description], [background/environment], [lighting]
```

**完整 prompt** = 前缀 + 模板（详见 `references/prompt-templates.md`）。

提交前对照 `references/prompt-templates.md` 底部的 **Prompt Construction Checklist** 逐项确认。

### Generation

使用 `nano_banana_batch_image_generation_v2` 一次并行生成 2 张：

```
nano_banana_batch_image_generation_v2(
  count=2,
  prompts=[faceless_prompt, puzzle_prompt],
  image_paths=[
    [original_portrait],
    [original_portrait]
  ],
  aspect_ratios=["9:16", "9:16"],
  model_name="nano_banana_2",
  resolution="2K"
)
```

如果批量生成失败，则逐张用 `nano_banana_image_generation` 生成。

---

## Phase 3: Quality Check & Retry

### Goal

用 `read_media` 对生成图进行质量评分，不合格的自动调整 prompt 重新生成。

### Input / Output

| | 内容 |
|---|------|
| **Input** | `faceless.png` + `puzzle.png` + 原始人像 |
| **Output** | 通过质检的 `faceless.png` + `puzzle.png`（可能经过重试替换） |

### 评分流程

详细评分标准、阈值和重试策略见 `references/quality-criteria.md`。

核心流程：

1. 将原图 + 两张生成图送入 `read_media`，按 `quality-criteria.md` 中的 Evaluation Prompt 评分
2. 解析评分结果，判断每张图是否 PASS（所有维度 ≥ 阈值）
3. FAIL 的图按 `quality-criteria.md` 中的 Retry Prompt Adjustment Strategy 调整 prompt，仅重生成不合格的那张
4. 最多重试 2 次，仍不合格则保留最佳版本
5. 将评分记录写入 `./.face-warp/{project_name}/quality_log.md`

### 关键阈值速查

| 图片 | 关键维度 | 阈值 |
|------|----------|------|
| faceless | face_concealment | ≥ 8 |
| faceless | character_consistency / natural_appearance / image_quality | ≥ 7 |
| puzzle | no_full_face | ≥ 8 |
| puzzle | feature_accuracy / skin_tone_consistency / artistic_quality | ≥ 7 |

---

## Phase 4: Composite (Faceless + Puzzle → Single Image)

### Goal

将通过质检的 faceless 和 puzzle 两张图左右拼接为一张完整的合成图。

### Input / Output

| | 内容 |
|---|------|
| **Input** | 通过质检的 `faceless.png` + `puzzle.png` |
| **Output** | `./.face-warp/{project_name}/output/composite.png` |

### 拼接方式

使用 `ffmpeg` 进行左右拼接，faceless 在左，puzzle 在右：

```
ffmpeg(args=[
  "-y",
  "-i", "./.face-warp/{project_name}/faceless.png",
  "-i", "./.face-warp/{project_name}/puzzle.png",
  "-filter_complex",
  "[0]scale=-1:1080[left];[1]scale=-1:1080[right];[left][right]hstack=inputs=2",
  "./.face-warp/{project_name}/output/composite.png"
])
```

**规则**：
- 两张图先统一高度（1080px），宽度等比缩放
- 使用 `hstack` 水平拼接（左: faceless, 右: puzzle）
- 输出到 `./.face-warp/{project_name}/output/composite.png`

---

## Completion

```
--- Face Warp Complete ---

Character: {character_description}
Output: .face-warp/{project_name}/output/composite.png
```

---

## Error Handling

| Error | Recovery |
|-------|----------|
| Portrait too low-res | Run `super_resolution` first |
| Face not clearly visible | Ask user for a clearer portrait |
| Batch generation fails | Fall back to single `nano_banana_image_generation` per image |
| Single image generation fails | Retry once with adjusted prompt, then skip and report |

## Anti-Patterns

- **Don't skip quality checks**: 质检是保证输出质量的关键环节，不能跳过
- **Don't alter body proportions**: 只改变面部呈现方式，不改变体型体态
- **Don't change clothing**: 服装必须与原图完全一致
- **Don't over-stylize**: 保持照片级写实感
- **Don't ignore skin tone**: 肤色一致性是人物一致性的关键