---
name: sophnet-id-photo
description: Sophnet 证件照：人脸检测后在多张达标脸中取面积最大者裁切头肩，VL 预审后换纯色底（白/蓝/红）并微调体态与角度。用户要证件照、换证件照底色、一寸/二寸/报名或电子证照底色时使用。
---

# Sophnet 一键证件照

## 用法

### 推荐流程（按顺序）

1. **输入图**：`--image` 仅 **1 张**；路径以 Media Understanding 解析到的为准。
2. **流水线（默认）**：**人脸检测**（置信度达标的人脸中**按框面积取最大**者做头肩裁切；零张达标则 `REJECT_REASON=no_face`）→ **VL 合规预审（裁切图**）→ **图改图**。多人同镜时 stderr 会有提示；stdout 在多于一张时可解析 **`FACE_DETECTED_COUNT`**、**`FACE_PICK=largest_area`**。
3. **合规与跳过**  
   - 若输出 **`STATUS=rejected`**：`REJECT_REASON` 常见为 `no_face`、`compliance_vlm`，或 **`--vl-description`** 关键词命中；按 **`REJECT_HINT`** 说明并**停止**。
   - **仅跳过 VL**：**`--skip-compliance-check`**（慎用）。  
   - **仅跳过检测与裁切**：**`--skip-face-crop`**（整张原图走 VL `full` 口径再审、再改图，慎用）。
4. **换底色**：**仍用同一张原始 `--image`**，参数与尺寸不变，**仅改 `--bg`** 再执行。

可选：**`--size`**（`800*1200` 默认 或 `960*1280`）、**`--dry-run`**（只校验参数不调 API）、**`--skip-face-crop`**（跳过人脸检测与头肩裁切，慎用）、**`--vl-description` / `--vl-description-file`**（关键词补充过滤）、**`--prompt`**（仅补充校正或构图说明）。底色 ID 见 **`--list-bg`**。

### 单独合规预审（可选）

对**整张原图**使用 `full` 规范（与 `id_photo_compliance.py` 默认一致）：

```bash
uv run {baseDir}/scripts/id_photo_compliance.py "media/inbound/images/a.jpg"
```

对已裁切头肩图使用精简规范（不强调合照）：

```bash
uv run {baseDir}/scripts/id_photo_compliance.py --scope cropped "/path/to/crop.jpg"
```

退出码：`0` 合规，`2` 不合规，`1` 错误；stdout 为一行 JSON。

### 生成白底（默认，含内置预审）

```bash
uv run {baseDir}/scripts/id_photo.py --image "media/inbound/images/a.jpg"
```

### 同一原图换蓝底 / 红底（再各执行一次）

```bash
uv run {baseDir}/scripts/id_photo.py --bg blue --image "media/inbound/images/a.jpg"
uv run {baseDir}/scripts/id_photo.py --bg red --image "media/inbound/images/a.jpg"
```

### 指定输出尺寸 960×1280（可与任意 `--bg` 组合）

```bash
uv run {baseDir}/scripts/id_photo.py --size "960*1280" --image "media/inbound/images/a.jpg"
```

### 查看 `--bg` 取值

```bash
uv run {baseDir}/scripts/id_photo.py --list-bg
```

### 仅校验参数（dry-run，不调 API、不预审）

```bash
uv run {baseDir}/scripts/id_photo.py --dry-run --image "media/inbound/images/a.jpg"
```

### 示例：`--vl-description` / `--prompt`

```bash
uv run {baseDir}/scripts/id_photo.py --image "media/inbound/images/a.jpg" --vl-description "单人正面半身照，脸部清晰，未戴口罩"
uv run {baseDir}/scripts/id_photo.py --image "media/inbound/images/a.jpg" --prompt "略提亮即可"
```

## 输出格式

**`id_photo.py`**（解析 stdout 键值行，便于脚本/Agent 处理）：

- 成功典型：`ID_PHOTO_BG`、`ID_PHOTO_BG_LABEL`、`ID_PHOTO_SIZE`、`FACE_CROP`、`COMPLIANCE_IMAGE_SCOPE`（未跑合规则无）、**`FACE_DETECTED_COUNT`** / **`FACE_PICK`**（仅检出多于一张达标脸时）、`INPUT_IMAGE_COUNT`、`STATUS=succeeded`、`OUTPUT_COUNT`、`IMAGE_URL`、`ALL_BG_TIP`；有时有 `PREVIEW_PATH`。
- 拒绝典型：`STATUS=rejected`、`REJECT_HINT`。其中 **`REJECT_REASON=no_face`** 为人脸检测门控；**`compliance_vlm`** 为 VL 不通过；关键词补充见 **`--vl-description`**。

**`id_photo_compliance.py`**：stdout 一行 JSON；退出码 `0` 合规，`2` 不合规，`1` 运行错误。

向用户回复时，若存在 **`ALL_BG_TIP`**，**原样带上**该段提示文案。

## 注意事项

- **能力边界**：默认人脸检测后在**多张达标脸中取框面积最大者**裁切；VL 看裁切区；图改图换底并做体态/角度等微调。**不**换脸、**不**美颜、**不**去掉光学眼镜。`--skip-face-crop` 时 VL 按整图 `full` 口径。
- 图片路径：用户上传多在 **`media/inbound/images/`**；须从 **Media Understanding** 日志取已解析路径（优先绝对路径），勿杜撰。
- **仅支持 1 张**输入图；找不到文件时让用户重传或提供可访问 URL。
- VL **裁切图**下主要拦截：口罩/墨镜、遮挡、双耳未露出；向用户说明时优先使用模型输出的 `COMPLIANCE_VIOLATIONS`。

## 回复模板

`xx`、`yy` 用当次结果的**中文口语**填写（如白底、竖版常用规格）；`IMAGE_URL` 为结果图链接。不应对用户粘贴脚本里的字段名。

```
✅ 证件照已生成
🎨 底色：xx
📐 尺寸：yy
🖼️ ![image](IMAGE_URL)
💡 还可换其它证件底色；若你有指定颜色，直接说「改成 xx 色」即可（常见：白、蓝、红）。
⚠️ 本内容含 AI 生成，图片约保存 24 小时，请及时下载。
```

若仅有本地预览路径，可在末尾再另起一行写出。
