AI 证件照 — Spec-Compliant ID Photos
你现在运行 id-photo 技能。目标：把用户随手拍的一张人像照片，一句话变成符合官方规格（中国一寸 / 二寸 / 护照、美签 2×2、日签…）的合规证件照，并产出一张可直接送打印店出片的六寸排版图。
全程走 Clawvard SDK 一方 service（service.clawvard.cv.image.idPhoto），底层是开源 HivisionIDPhotos（Apache-2.0）的 MTCNN/RetinaFace 人脸检测 + MODNet/BiRefNet 抠图 + 规格化排版。
前置条件
- Node ≥ 18（任意主流 OS：macOS / Linux / Windows）。
- 已在
https://clawvard.school控制台登录并取得 Clawvard API key。 - 安装 Clawvard SDK ≥ 0.5.0 —— 这是引入
cv.image.idPhoto的最低版本。 - 输入图建议短边 ≥ 600 px、单人正脸、自然光线即可；不需要专业证件馆光。
不需要：本地 ONNX、Python、模型权重、私有 clawvard 仓库、第三方账号。
安装
npm i @clawvard/sdk@^0.5.0
# 或：pnpm add @clawvard/sdk@^0.5.0 / yarn add @clawvard/sdk@^0.5.0
一、随手拍 → 合规证件照（generate）
import { readFile } from "node:fs/promises";
import { Clawvard, NoFaceDetectedError, MultipleFacesError } from "@clawvard/sdk";
const cv = new Clawvard({ apiKey: process.env.CLAW_API_KEY! });
// 1) 读用户自拍并转 data URL（也支持 https URL 或纯 base64）
const bytes = await readFile("./me.jpg");
const dataUrl = `data:image/jpeg;base64,${bytes.toString("base64")}`;
// 2) 中国一寸 · 蓝底 · 295×413
const cnBlue = await cv.image.idPhoto.generate({
image: dataUrl,
spec: "cn_1inch",
bgColor: "#438EDB",
});
console.log(`中国一寸：${cnBlue.widthPx}×${cnBlue.heightPx} px @ ${cnBlue.widthMm}×${cnBlue.heightMm} mm`);
// → 中国一寸：295×413 px @ 25×35 mm
generate() 返回：
| 字段 | 含义 |
|---|---|
standardPng |
4 通道透明 PNG（无底色），合成 / 二次修图用 |
standardJpg |
带底色的成品 JPG（用户直接拿这张） |
hdJpg |
高清版 —— 像素更多，专为打印准备 |
widthPx / heightPx |
实际像素尺寸（一定等于 spec） |
widthMm / heightMm |
对应毫米尺寸（打印店认这个） |
spec |
回传的 spec id，方便记录 |
支持的 spec（GA 阶段）
| spec id | 用途 | 像素 | 毫米 |
|---|---|---|---|
cn_1inch |
中国一寸（求职、办证） | 295 × 413 | 25 × 35 |
cn_2inch |
中国二寸（简历、考试） | 413 × 579 | 35 × 49 |
cn_passport |
中国护照 | 390 × 567 | 33 × 48 |
us_visa_2x2 |
美签 / 护照 2×2 | 600 × 600 | 51 × 51 |
jp_visa |
日本签证 | 531 × 531 | 45 × 45 |
后续新增规格走 SDK minor bump —— bump npm i Clawvard SDK 即可。
常见 bgColor
| 用途 | hex |
|---|---|
| 中国蓝底 | #438EDB |
| 纯白底（美签 / 护照） | #FFFFFF |
| 中国红底（简历 / 求职） | #D9534F |
二、合规证件照 → 六寸排版打印图（layout）
拿到 standardJpg 后，再调一次 layout，把它拼成一张可直接送打印店的六寸卡片（中国一寸默认 8 张 / 张）：
const sheet = await cv.image.idPhoto.layout({
standardJpgUrl: cnBlue.standardJpg, // 上一步的成品 JPG
sheet: "6inch", // 默认值，也可以 "5inch" / "A4" / "3R" / "4R"
});
console.log(`排版：${sheet.rows} × ${sheet.cols}，共 ${sheet.copiesPerSheet} 张`);
// → layoutJpg 直接发到照相馆 / 自助打印机
三、常见报错（必须处理）
cv.image.idPhoto.* 会抛出类型化错误，让 agent 给用户准确的下一步指引：
| 错误类 | 含义 | 建议回复 |
|---|---|---|
NoFaceDetectedError |
图里没检测到人脸 | 让用户换一张清晰、正脸、有光的人像照片 |
MultipleFacesError |
图里有多张脸 | 让用户裁到只剩自己 |
FaceNotCenteredError |
人脸明显偏离规格中心 | 让用户重拍：头部居中、肩部水平 |
FaceTooSmallError |
人脸太小（离相机太远 / 图太小） | 让用户靠近相机重拍，或换更高分辨率原图 |
MattingFailedError |
抠图失败（头发过密 / 背景过乱） | 换 mattingModel: "birefnet" 或 "rmbg" 再试一次 |
UnsupportedSpecError |
spec id 服务端不识别 | 升级 Clawvard SDK 到最新版（命令见课程页 install 行） |
IdPhotoWorkerUnavailableError |
后端 Hivision worker 暂时不可达 | 稍后重试；持续失败联系 Clawvard 客服 |
最小处理示例：
try {
await cv.image.idPhoto.generate({ image: dataUrl, spec: "cn_1inch", bgColor: "#438EDB" });
} catch (err) {
if (err instanceof NoFaceDetectedError) {
console.error("没识别到人脸 —— 请重新提交一张正脸自拍。");
} else if (err instanceof MultipleFacesError) {
console.error("照片里有多个人 —— 请只保留你自己。");
} else {
throw err;
}
}
关键规则
- 所有 service 调用走官方 Clawvard SDK 的 typed import；
- 用户文案、SOP、链接只用
https://clawvard.school； - 课程只依赖公开 npm 包，不要求用户 clone 私有仓库；
generate()与layout()各按 1 credit 扣费 —— 失败的NoFaceDetectedError/MultipleFacesError/MattingFailedError会自动退款；- 输入图 ≤ 20 MB；过大先在本地 resize。
学习完成后
告诉用户：
我已经学会了 id-photo。给我一张你的自拍（路径或 https URL），告诉我要哪种规格（中国一寸蓝底 / 美签 2×2 白底 / 中国护照…），我用 Clawvard SDK 的
cv.image.idPhoto一句话给你出合规证件照，再用layout给你一张可直接送打印店的六寸排版图。零第三方 key、零本地模型、不需要 clone 任何仓库。