证件照制作

接口标识: idphoto 价格: 0.5 元/次异步响应

接口介绍
接口文档
在线测试

接口简介

证件照制作接口把一张正面人像照片自动制成标准证件照：人像抠图、按人脸构图裁剪、更换底色，支持一寸、小一寸、二寸、护照、美国签证规格与自定义毫米尺寸；底色含白、蓝、红、任意十六进制色值与渐变，DPI 72~600 可调，可同步产出五寸至 A4 排版冲印照。自动预检照片适合度，不适合时返回原因与拍摄建议；可选轻度美颜，不改变五官脸型。适合求职、签证与各类证照办理场景。【调用约定】本接口为任务类：返回的 task_id 需调用 taskresult 查询终态结果（output_status 为 finish 或 fail）；status 为 not 或 processing 时请每隔5-10秒重复查询直至终态。

详细介绍

![证件照制作接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_idphoto__1794363419_029e2ad9e4e8.png)

求职、签证、社保卡等线上办理场景都需要标准证件照，去照相馆重拍费时费钱。证件照制作接口把一张正面人像照片自动制成合规证件照与冲印排版照。

## 接口概述
面向线上证照办理、招聘平台、签证服务与证件照小程序等场景，上传一张正面免冠人像照片并指定规格与底色，接口自动完成人像抠图、按人脸构图裁剪、底色合成与可选轻度美颜，产出符合毫米尺寸与 DPI 要求的标准证件照，默认还同步输出六寸排版冲印照，多产物自动打包。本接口为异步任务模式：提交后返回任务 ID，凭任务 ID 经 taskresult 接口查询最终结果。制作前会自动预检照片适合度，对无人脸、多人脸、人脸过小、头部倾斜过大、明显侧脸等不适合的照片，任务仍以成功状态结束并返回原因与拍摄建议，便于业务系统引导用户重拍。

## 核心能力
1. **规格全覆盖**：一寸 25×35mm、小一寸 22×32mm、二寸 35×49mm、护照 33×48mm、美国签证 51×51mm 预设，支持自定义毫米尺寸，输出 DPI 72~600 可调、默认 300，满足冲印要求。
2. **底色多样**：白、蓝、红三色预设，任意十六进制色值，以及上下渐变、中心向四周渐变效果。
3. **冲印排版**：可同步输出排版冲印照，纸张支持五寸、六寸、七寸与 A4，多产物自动打包。
4. **适合度预检**：照片不适合时返回具体原因与拍摄建议；偏暗、偏亮、清晰度偏低等轻度瑕疵照常出片并附提示。
5. **轻度美颜**：可选美白、磨皮、微提亮，力度保守，不改变五官脸型，不影响证件照可用性与人脸识别。

## 产品优势
1. **全自动制作**：抠图、裁剪、换底色、排版一次完成，替代照相馆人工修图。
2. **本地引擎**：人像抠图与人脸检测在平台服务器本地运行，不依赖第三方模型服务。
3. **失败语义友好**：照片不适合时任务按成功结束并给出原因与建议，业务方可做精细化引导。
4. **冲印即取**：标准照与排版照一次产出，用户可直接拿去冲印店打印。
5. **准确规范**：像素尺寸按毫米规格与 DPI 精确换算，构图按人脸位置自动裁剪。

## 效果展示
一句话理解：它就像把照相馆的「证件照一条龙」搬到线上——交一张照片、报规格和底色，标准照和冲印排版照一起做好交给你。

本接口为异步任务模式：提交后先拿到任务 ID，再凭任务 ID 经 taskresult 查询最终结果。以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| file | https://example.com/demo/portrait.jpg | 人像照片，需含清晰正面免冠人脸，JPG/JPEG/PNG 格式，单图不超过 10MB |
| spec | one_inch | 规格：一寸 one_inch（默认）、小一寸、二寸、护照、美签，或 custom 自定义毫米尺寸 |
| bg_color | white | 底色：white（默认）/ blue / red、十六进制色值或渐变预设 |
| dpi | 300 | 输出分辨率 72~600，默认 300，冲印建议 300 及以上 |
| layout_size | six_inch | 排版照纸张：six_inch 六寸（默认）/ five_inch / seven_inch / a4 |

你会拿到的结果（凭 task_id 经 taskresult 查询、output_status=finish 时的异步结果）：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 任务状态 | `"finish"` | `output_status`，finish 表示制作完成 |
| 证件照与排版照地址 | 下方示例中的两个地址（逗号分隔） | `output_content`，多产物时为各产物地址逗号拼接 |
| 打包下载地址 | https://fujian.phpwc.com/pyapi/uploads/api/20261110/idphoto_20261110_190000.zip | `output_dourl`，标准照与排版照打包为一个压缩包 |
| 制作详情 | 规格、像素尺寸、DPI、底色等 | `output_info`，含文件名、规格、适合度结论与提示等 |

API请求示例：

```text
POST /api/idphoto
file=https://example.com/demo/portrait.jpg&spec=one_inch&bg_color=white&dpi=300&layout_size=six_inch&beauty=0
```

API响应示例（taskresult 查回的最终异步结果）：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "task_id": "acK3v9x2LmQ7pR4tY8wZ1b",
    "serialnumber": "",
    "jk_mark": "idphoto",
    "output_status": "finish",
    "output_content": "https://fujian.phpwc.com/pyapi/uploads/api/20261110/idphoto_20261110_190000.png,https://fujian.phpwc.com/pyapi/uploads/api/20261110/idphoto_layout_six_inch_20261110_190000.png",
    "output_dourl": "https://fujian.phpwc.com/pyapi/uploads/api/20261110/idphoto_20261110_190000.zip",
    "output_info": {
      "file_name": "idphoto.png,idphoto_layout_six_inch.png",
      "spec": "one_inch",
      "width_px": 295,
      "height_px": 413,
      "dpi": 300,
      "bg_color": "FFFFFF",
      "layout_size": "six_inch",
      "suitable": true,
      "warnings": []
    },
    "output_time": 18,
    "output_msg": "处理完成"
  },
  "request_id": "req-idphoto-demo-001"
}
```

一寸照在 300 DPI 下换算为 295×413 像素；默认标准照与六寸排版照两个产物一起输出，output_content 为两个地址逗号拼接、output_dourl 为 zip 打包地址；若关闭排版则只有标准照一个产物，两者为同一地址。照片不适合做证件照时，任务状态仍为 finish，output_content 为不适合原因文本，output_info 附拍摄建议，不产出文件。

## 应用场景
1. **招聘平台**：求职者上传自拍即得各规格简历照，无需跑照相馆。
2. **签证留学服务**：按目标国规格产出护照照、美签照，配排版照直接冲印邮寄。
3. **政务校园办理**：社保卡、学生证、考试报名等线上材料提交场景。
4. **证件照小程序**：以之为核心制作能力，提供规格切换与底色试选。
5. **企业工牌**：新员工提交照片后统一产出工牌尺寸、统一底色的照片。

## 应用案例
一款求职类应用此前让用户自行上传照片，规格与底色五花八门，常被用人单位退回；接入接口后自动制作标准一寸白底照片，照片不适合时即时返回原因与拍摄建议，用户当场知道怎么重拍，简历照通过率明显提升。

一家签证服务社要为每位客户同时提供电子版与冲印版照片，过去靠修图师逐张处理；现在客户上传照片后系统按目标国规格制作，标准照与排版照一次打包交付，制作周期大幅缩短。

一家证件照自助终端厂商把接口作为后台制作引擎：用户在终端前完成拍摄，屏幕上选规格与底色，制作完成后终端直接打印并把电子版发到用户手机，门店无需常驻摄影人员。

常见问题

Q：提交后怎么拿到证件照？

A：提交成功返回 task_id，凭 task_id 调用平台的 taskresult 接口查询；output_status 为 finish 时，output_dourl 即产物打包地址，output_content 为各产物的单独地址（逗号分隔）。

Q：上传的照片不适合做证件照会怎样？

A：接口会预检照片适合度：无人脸、多人脸、人脸过小、头部倾斜过大或明显侧脸的照片不产出文件，但任务仍按成功结束，output_content 给出不适合原因，output_info 给出拍摄建议，便于引导用户重拍。

Q：支持哪些规格和底色？

A：预设一寸、小一寸、二寸、护照、美国签证五种规格，支持自定义毫米尺寸；底色有白、蓝、红预设与任意十六进制色值，还支持上下渐变与中心向四周渐变效果。

Q：开启美颜会影响证件照合规使用吗？

A：beauty=1 仅做轻度美白、磨皮与微提亮，力度保守，不改变五官与脸型，不影响证件照可用性与人脸识别。

证件照一寸照换底色排版照签证照片人像抠图

接口地址： https://www.phpwc.cn/api/idphoto

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`file`	string	必填	-	人像照片，公网URL / Base64(data:开头) / 文件ID(fileid_开头)，需含清晰正面免冠人脸；格式 JPG/JPEG/PNG，单图不超过 10MB（硬限制，超限返回参数错误）
`spec`	string	选填	`one_inch`	证件照规格：one_inch 一寸25×35mm（默认）/ small_one_inch 小一寸22×32mm / two_inch 二寸35×49mm / passport 护照33×48mm / visa_us 美国签证51×51mm / custom 自定义（须配 custom_width_mm、custom_height_mm）
`custom_width_mm`	float	选填	-	自定义宽度（毫米），仅 spec=custom 时必填，如 25
`custom_height_mm`	float	选填	-	自定义高度（毫米），仅 spec=custom 时必填，如 35
`bg_color`	string	选填	`white`	背景色：white 白（默认）/ blue 蓝 / red 红 / 自定义十六进制如 FFFFFF 或 438EDB；支持渐变：gradient_blue / gradient_gray / gradient_red 预设，或 gradient:RRGGBB（上→下渐变到白）、gradient_center:RRGGBB（中心→四周渐变到白）
`dpi`	int	选填	`300`	输出分辨率 DPI，72~600，默认 300（冲印建议 300 或 413）
`layout`	bool	选填	`true`	是否额外输出排版冲印照，默认 true；纸张规格由 layout_size 指定（默认六寸 1795×1205px @300dpi）；face_crop=false 时本项不生效
`layout_size`	string	选填	`six_inch`	排版照纸张规格：six_inch 六寸/4R 1795×1205（默认）/ five_inch 五寸/3R 1500×1050 / seven_inch 七寸/5R 2100×1500 / a4 A4纵向 2480×3508；仅 layout=true 且 face_crop=true 时生效
`face_crop`	bool	选填	`true`	是否按人脸自动裁剪构图（头身比调整），默认 true；false 时仅抠图换底色、保持原图尺寸构图
`beauty`	int	选填	`0`	是否开启轻度美颜：0 不开启（默认）/ 1 开启。含美白 + 磨皮 + 微提亮/对比度/锐化，力度保守，不改变五官脸型，不影响证件照可用性与人脸识别
`serialnumber`	string	选填	-	开发者自定义查询编号（可选，不传则无），同接口下不可重复，用于幂等控制和 taskresult 查询

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`task_id`	string	任务ID，用于通过 taskresult 接口查询任务结果
`serialnumber`	string	调用方传入的 serialnumber，用于通过 taskresult 接口查询任务结果
`task_msg`	string	任务提示信息（含预计耗时），随后经 taskresult 查询结果
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

异步响应字段（调用 taskresult 返回）

本接口为异步任务类：提交后立即返回 task_id，需再调用 taskresult（传 task_id 或 serialnumber）查询结果，返回字段如下。

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	任务结果数据
`task_id`	string	任务ID（与提交响应一致）
`serialnumber`	string	调用方传入的 serialnumber（未传则为空串）
`jk_mark`	string	原调用接口标识
`output_status`	string	任务状态：not=未开始 / processing=处理中 / finish=完成 / fail=失败
`output_content`	string	完成后的文本结果（如翻译全文、问答答案），无则为空串
`output_dourl`	string	完成后的产物下载地址（图片/文档/音视频），无则为空串
`output_info`	object	任务明细数据（随接口不同，见子字段）
`output_msg`	string	任务说明 / 状态提示文案
`output_time`	int	任务耗时（秒）
`request_id`	string	请求追踪ID

taskresult 响应 JSON 示例：

{
  "code": 0,
  "desc": "success",
  "data": {
    "task_id": "任务ID",
    "serialnumber": "调用方传入的流水号",
    "jk_mark": "idphoto",
    "output_status": "finish",
    "output_content": "文本结果（无则空）",
    "output_dourl": "产物下载地址（无则空）",
    "output_info": { },
    "output_msg": "任务完成提示",
    "output_time": 12
  },
  "request_id": "abc123..."
}

请先登录后使用在线测试