电子照助手开放API文档
www.dianzizhao.com API
欢迎使用电子照助手
Hi，开发者您好，欢迎使用电子照助手的API，您将通过调用API获得电子照助手在证件照领域每年服务百万级用户而积累的技术成果，帮助您开展稳定可靠的证件照业务。以下内容，是您接入服务的一些基本介绍，希望您能够在这里找到适合您业务的AI技术能力，感谢您的使用！
这是一个使用电子照助手API接口实现的证件照网站，支持PC端和移动端：http://zjz.dianzizhao.com
快速开始
获取 API Key
* 新用户免费赠送1000点
示例下载
以下demo中包含了Java、PHP、Python、.Net/C#语言的调用示例，也支持前端直接调用(Vue、各平台小程序)。
注：
1. Http状态码401时表示您的APIKEY没有通过API网关验证，请检查您的APIKEY是否有效
2. 文件大小不超过10mb
购买API账号点数
调用部分接口需消耗账户api点数，api点数需要充值购买，充值入口
购买api点数≥2000元赠送证件照制作网站：点击试用
POST 1. 证件照预览
地址：https://www.dianzizhao.com/api/open/idphoto?type=preview
请求头（Header）
（必填） Content-Type：application/x-www-form-urlencoded
（必填） X-API-KEY： 您的API Key
参数
| 参数名 | 说明 | 是否必填 | 示例值 | 类型 |
|---|---|---|---|---|
| croppedImage | 预处理图片，Base64字符串格式。 您可以在您的程序中提前将照片进行裁剪、旋转、压缩等处理。 |
必填 | 不包含“base:image/jpg;base64,” | string |
| width | 证件照图片宽度，单位为像素（px） | 必填 | 295 | string |
| height | 证件照图片高，单位为像素（px） | 必填 | 413 | string |
| resolution | 证件照图片分辨率，单位为DPI。 默认值为300，社保卡/退役军人优待证/身份证等请使用350分辨率或更高 |
可选 | 300 | string |
| filetype | 文件格式，可选项为jpg/png，默认为jpg。 | 可选 | jpg | string |
| sizemin | 证件照文件压缩的最小KB，默认值为10。 | 可选 | 10 | string |
| sizemax | 证件照文件压缩的最大KB，默认值为1024。 | 可选 | 50 | string |
| sizeunit | 证件照文件压缩的单位，默认值为KB。 | 可选 | KB | string |
| color |
证件照底色（背景颜色）。 1、当filetype为png时，color值为null则返回透明背景证件照。 2、当filetype为jpg时，color值为null或空则返回原图背景（不更换背景色） 3、标准证件照背景色：white（白色）/red（红色）/dark_red（深红色）/blue（标准蓝色）/tint（浅蓝色）/dark_blue（深蓝色）/gray（灰色） 4、渐变背景色（垂直方向）：格式为“起始色值,结束色值”，例如： 蓝白渐变：#3492C4,#ffffff 灰白渐变：#9c9c9c,#f9f9f9 浅蓝渐变：#6cb8f3,#d5eeff 红白渐变：#c90507,#f8e1e1 5、渐变背景色（圆心径向）：格式为“起始色值~结束色值” 6、自定义纯色：格式为“色值”，例如：#c41f34 更多色值您可参考：https://www.dianzizhao.com/dp |
可选 | red | string |
| advanced | 证件照AI高清修复，可大幅度提高照片清晰度并修复低质量照片 | 可选 | false | bool |
| appendtext | 附加文字，不超过20个字符（中文按2字符计算），文字将出现在照片底部 | 可选 | 103班-张三 | string |
| headtop | 证件照头顶留白距离，即人像头顶距离上边距的像素距离，与headtoprange参数配合使用，用于限定照片中头顶留白距离。 | 可选 | 20 | string |
| headtoprange | 证件照头顶留白距离的浮动范围，与headtop参数配合使用。 例如，您要限定照片头顶留白标准距离为20像素，并且头顶留白距离在10~30像素之间均可，您可以设置headtop=20，headtoprange=10。 |
可选 | 10 | string |
| headmax | 证件照中头部高度最大占比，计算方式为：证件照高度/头部高度。 例如，某证件照要求头部高度最大为300像素，证件照高度为480像素，则headmax=480/300=1.6。 |
可选 | 1.3 | string |
| headmin | 证件照中头部高度最小占比，计算方式为：证件照高度/头部高度。 例如，某证件照要求头部高度最小为200像素，证件照高度为480像素，则headmax=480/300=2.4。 |
可选 | 1.5 | string |
| quality |
是否对证件照质量进行检查，检查项包括照片过暗、照片模糊、是否为卡通人脸、是否过度美颜、多张人脸、人脸不完整 可选值：true/false 开启后照片检测结果将在返回结果的warn字段，以英文半角分号分隔，具体包括： 1、是否包含人像 2、照片模糊 3、照片过暗 4、非真实人脸（美颜过度、卡通） 5、是否佩戴眼镜 6、多张人脸 7、眼睛是否闭合 8、眼睛是否水平 9、人脸角度不正 10、是否佩戴口罩 11、情绪 12、性别 13、年龄 14、鼻子遮挡 15、下巴遮挡 16、左右脸颊遮挡 17、是否为合同图（概率） |
可选 | false | bool |
| rotate | 图片旋转角度，顺时针为正整数，逆时针为负整数 | 可选 | 5 | int |
| autotone | 美颜——自动色调，可优化照片偏色，增强色彩真实感 | 可选 | true | bool |
| autodefreckle | 美颜——自动祛斑，可自动识别并去除脸部斑、痘、痣 | 可选 | true | bool |
| face_white | 美颜——肤色美白，设定值范围：0~100 | 可选 | 60 | int |
| face_soften | 美颜——磨皮，可增加皮肤光滑度，设定值范围：0~100 | 可选 | 60 | int |
| face_thin | 美颜——瘦脸，设定值范围：0~100 | 可选 | 60 | int |
| face_eye | 美颜——大眼，可增大眼睛，设定值范围：0~100 | 可选 | 60 | int |
| eyebag_removal | 美颜——祛眼袋，可减轻眼袋范围和颜色，设定值范围：0~100 | 可选 | 60 | int |
| hignnose | 美颜——高鼻梁，设定值范围：0~100 | 可选 | 60 | int |
| face_light | 美颜——脸部亮度，设定值范围：0~100 | 可选 | 60 | int |
| eye_light | 美颜——亮眼，设定值范围：0~100 | 可选 | 60 | int |
返回
Http状态码为 200 时返回Json，包含证件照预览图片的Base64字符串，格式示例：
{ code : 0, msg : "", image:"证件照预览图base64字符串",width:480,height:640,size:"138", photoid:"543AB***2020" }| 参数 | 说明 | 示例 | 类型 |
|---|---|---|---|
| code | 状态码 | 0 | int |
| msg | 消息 | 成功 | string |
| photoid | 证件照编号，用于下载证件照无水印文件用（详见接口文档：2.证件照下载） | - | string |
| image | 证件照预览图base64字符串 | /9j/4QAYRXhpZgAASUkqAAg************LW5zIy== | string |
| width | 宽度 | 360 | int |
| height | 高度 | 480 | int |
| size | 文件大小（KB） | 28 | string |
| warn |
照片建议 您可根据返回的照片问题（英文半角分号分隔），自行判断是否属于合格照片，本接口返回的问题项包括： 照片模糊 左眼疑似闭合 左眼闭合 右眼疑似闭合 右眼闭合 左脸颊有遮挡 右脸颊有遮挡 非真实人脸 佩戴眼镜 双眼未保持水平 多张人脸 未检测到真实人脸 人像面部过暗 人像面部不完整 原图较小导致照片模糊 光线或清晰度不佳，建议重新拍摄 头部未朝向正前方，请保持双眼平视前方 头部姿态不端正，请保持双眼平视前方 衣服颜色与背景接近，建议更换 |
- | string |
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
| 照片尺寸过大，无法处理 | 照片宽度或高度超过5000像素，请先压缩尺寸再提交接口 |
| 压缩范围不支持处理 | sizemin设置不得大于3000KB |
| 未找到合格人像，抠图失败，请更换照片 | 照片模糊、低质量、不包含人像，请更换清晰完整的单人正面免冠照 |
| 照片裁剪尺寸过大或者过小，请重新裁剪。 | - |
| 当前使用人数较多，请稍等重试 | 超过QPS限制，请稍后重试 |
| 照片不符合要求 | 照片人像方向错误、模糊等导致，请更换清晰完整的单人正面免冠照 |
GET 2. 证件照下载
地址：https://www.dianzizhao.com/api/open/idphoto/download
参数 [Header]
| 参数名 | 说明 | 是否必填 | 类型 |
|---|---|---|---|
| X-API-Key | 密钥 | 必填 | string |
参数 [Query]
| 参数名 | 说明 | 是否必填 | 类型 |
|---|---|---|---|
| photoid | 证件照编号，来源于证件照预览接口的返回值 | 必填 | string |
| audit |
报名平台上传照片如果需要照片审核工具审核后再上传，本平台接口可自动审核，支持国内绝大多数审核工具。 下面以“报名平台-参数值”的方式列举： 中国人事考试网 - cpta 中国卫生人才网 - 21wecan 全国人事考试服务平台 - zgkshg 军队文职考试 - zgkshg 使用“智韬科技”照片审核工具的报名系统 - zhitao 使用“诺玛信nomax”照片审核工具的报名系统 - nomax 使用“诺玛信nomax”新版照片审核工具的报名系统 - nomax2024 国家消防救援报名 - 119 |
可选 | string |
| color |
如果照片审核工具为“诺玛信nomax”、“智韬科技”，则需要传该参数 本参数值由照片背景色决定： 红色 - red 蓝色 - blue 白色 - white |
可选 | string |
返回
Http状态码为 200 时返回图片流（即：ContentType=image/jpg），请自行保存图片文件，建议同时保存photoid参数（相同photoid参数调用下载接口不重复计费）
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
| API账号点数不足 | 当前API账号点数余额不足以支付本次下载，请及时充值 |
| 证件照下载失败，请检查photoid是否正确 | photoid参数不正确 |
POST 3. 证件照排版预览
地址：https://www.dianzizhao.com/api/open/paiban/preview
请求头（Header）
（必填） Content-Type：application/x-www-form-urlencoded
（必填） X-API-KEY： 您的API Key
参数
| 参数名 | 说明 | 是否必填 | 示例值 | 类型 |
|---|---|---|---|---|
| source | 预处理图片，Base64字符串格式。 支持多张照片混排，传入多个source参数即可。 如传入photoid则source可不填 |
非必填 | 不包含“base:image/jpg;base64,” | string array |
| photoid | 从接口《1.证件照预览》接口获得的photoid。 如传入source则photoid可不填 |
非必填 | 647A7****A8969F8155 | string array |
| photosize | 证件照尺寸 | 必填 |
可选值： 一寸照片 二寸照片 三寸照片 四寸照片 五寸照片 大一寸照片 小一寸照片 小二寸照片 大二寸照片 40-50mm 51-51mm 35-40mm 结婚登记照 |
string |
| papersize | 打印证件照相纸尺寸 | 必填 |
可选值： 五寸相纸 六寸相纸 七寸相纸 八寸相纸 十寸相纸 十二寸相纸 A4 |
string |
返回
Http状态码为 200 时返回Json，包含证件照预览图片的Base64字符串，格式示例：
{ code : 0, image:"证件照排版预览图base64字符串",photoid : "" }| 参数 | 说明 | 示例 | 类型 |
|---|---|---|---|
| code | 状态码 | 0 | int |
| msg | 消息 | 成功 | string |
| photoid | 证件照排版编号，用于下载证件照排版无水印文件用（详见接口文档：4.证件照排版下载） | - | string |
| image | 证件照排版预览图base64字符串 | /9j/4QAYRXhpZgAASUkqAAg************LW5zIy== | string |
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
POST 4. 证件照排版下载
地址：https://www.dianzizhao.com/api/open/paiban/download
请求头（Header）
（必填） Content-Type：application/x-www-form-urlencoded
（必填） X-API-KEY： 您的API Key
参数
| 参数名 | 说明 | 是否必填 | 示例值 | 类型 |
|---|---|---|---|---|
| source | 预处理图片，Base64字符串格式。 支持多张照片混排，传入多个source参数即可。 |
必填 | 不包含“base:image/jpg;base64,” | string array |
| photosize | 证件照尺寸 | 必填 |
可选值： 一寸照片 二寸照片 三寸照片 四寸照片 五寸照片 大一寸照片 小一寸照片 小二寸照片 大二寸照片 40-50mm 51-51mm 35-40mm 结婚登记照 |
string |
| papersize | 打印证件照相纸尺寸 | 必填 |
可选值： 五寸相纸 六寸相纸 七寸相纸 八寸相纸 十寸相纸 十二寸相纸 A4 |
string |
| photoid | 通过《1.证件照预览》接口获得的photoid | 必填 | string |
返回
Http状态码为 200 时返回图片流
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
POST 5. 证件照换装预览
地址：https://www.dianzizhao.com/api/open/changeclothes
请求头（Header）
（必填） Content-Type：application/x-www-form-urlencoded
（必填） X-API-KEY： 您的API Key
参数
| 参数名 | 说明 | 是否必填 | 示例值 | 类型 |
|---|---|---|---|---|
| picurl | 照片网络地址 您还可以通过file（上传照片文件）、photoid（1.证件照预览接口返回的photoid）的方式提交需要换装的照片 |
选填 | https://www.abc.com/image.jpg | string |
| file | 照片文件 仅支持jpg/jpeg/png格式文件，您还可以通过picurl（远程文件）、photoid（1.证件照预览接口返回的photoid）的方式提交需要换装的照片 |
选填 | 图片文件 | 文件 |
| photoid | 证件照预览id 接口返回的photoid，您还可以通过picurl（远程文件）、file（上传照片文件）的方式提交需要换装的照片 |
选填 | 647A7A7A**********2020202020 | 文件 |
| width | 证件照图片宽度，单位为像素（px） | 必填 | 295 | string |
| height | 证件照图片高，单位为像素（px） | 必填 | 413 | string |
| resolution | 证件照图片分辨率，单位为DPI。 默认值为300，社保卡/退役军人优待证/身份证等请使用350分辨率或更高 |
可选 | 300 | string |
| filetype | 文件格式，可选项为jpg/png，默认为jpg。 | 可选 | jpg | string |
| sizemin | 证件照文件压缩的最小KB，默认值为10。 | 可选 | 10 | string |
| sizemax | 证件照文件压缩的最大KB，默认值为1024。 | 可选 | 50 | string |
| color |
证件照底色（背景颜色）。 1、当filetype为png时，color值为null则返回透明背景证件照。 2、当filetype为jpg时，color值为null或空则返回原图背景（不更换背景色） 3、标准证件照背景色：white（白色）/red（红色）/dark_red（深红色）/blue（标准蓝色）/tint（浅蓝色）/dark_blue（深蓝色）/gray（灰色） 4、渐变背景色（垂直方向）：格式为“起始色值,结束色值”，例如： 蓝白渐变：#3492C4,#ffffff 灰白渐变：#9c9c9c,#f9f9f9 浅蓝渐变：#6cb8f3,#d5eeff 红白渐变：#c90507,#f8e1e1 5、渐变背景色（圆心径向）：格式为“起始色值~结束色值” 6、自定义纯色：格式为“色值”，例如：#c41f34 更多色值您可参考：https://www.dianzizhao.com/dp |
可选 | red | string |
| appendtext | 附加文字，不超过20个字符（中文按2字符计算），文字将出现在照片底部 | 可选 | 103班-张三 | string |
| clothes_id | 换装服装的编号 | 必填 | 点击下载可选服装缩略图，服装编号即文件名中的数字 | int |
返回
Http状态码为 200 时返回Json，包含证件照预览图片的Base64字符串，格式示例：
{ code : 0, msg : "", image:"证件照预览图base64字符串", photoid:"65AB12***2020"}| 参数 | 说明 | 示例 | 类型 |
|---|---|---|---|
| code | 状态码 | 0 | int |
| msg | 消息 | 成功 | string |
| photoid | 证件照换装编号，用于下载证件照无水印文件用（详见接口文档：6.证件照换装下载） | 647A7A7A73202020202020205686F0D4644B54E93C433AA0F0A541BE6EFDC2D | string |
| image | 证件照换装预览图base64字符串 | /9j/4QAYRXhpZgAASUkqAAg************LW5zIy== | string |
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
| 照片尺寸过大，无法处理 | 照片宽度或高度超过5000像素，请先压缩尺寸再提交接口 |
| 压缩范围不支持处理 | sizemin设置不得大于3000KB |
| 未找到合格人像，抠图失败，请更换照片 | 照片模糊、低质量、不包含人像，请更换清晰完整的单人正面免冠照 |
| 照片裁剪尺寸过大或者过小，请重新裁剪。 | - |
| 当前使用人数较多，请稍等重试 | 超过QPS限制，请稍后重试 |
| 照片不符合要求 | 照片人像方向错误、模糊等导致，请更换清晰完整的单人正面免冠照 |
支持200余种男装、女装、儿童装一键智能换装
如遇问题请联系技术客服微信（微信号：cdipbsxf），点击在线试用换装功能
GET 6. 证件照换装下载
地址：https://www.dianzizhao.com/api/open/changeclothes/download
参数 [Header]
| 参数名 | 说明 | 是否必填 | 类型 |
|---|---|---|---|
| X-API-Key | 密钥 | 必填 | string |
参数 [Query]
| 参数名 | 说明 | 是否必填 | 类型 |
|---|---|---|---|
| photoid | 证件照编号，来源于5.证件照换装预览接口的返回值 | 必填 | string |
返回
Http状态码为 200 时返回图片流（即：ContentType=image/jpg），请自行保存图片文件，建议同时保存photoid参数（相同photoid参数调用下载接口不重复计费）
Http状态码为 400 时表示处理错误并返回Json，格式示例：
{msg:"错误提示"}| 错误提示 | 原因及解决办法 |
|---|---|
| 未授权的APIKey | APIKey不正确或已欠费，请检查、续费或联系客服（微信：cdipbsxf） |
| APIKey已停用 | APIKey已被停用 |
| APIKey已过期 | APIKey已过期 |
| API账号点数不足 | 当前API账号点数余额不足以支付本次下载，请及时充值 |
| 证件照下载失败，请检查photoid是否正确 | photoid参数不正确 |
7. 证件照批量处理
用户可上传Zip格式压缩包，接口将保持原有文件目录及文件名，并批量将压缩包中的所有图片处理成设定的尺寸，适用于相同尺寸大量证件照的统一处理。
接口效果预览：批量证件照处理
目前此接口仅对部分合作伙伴开放。
8. 行业解决方案
电子照助手API客户应用包括：证件照云冲印、自助证件照打印设备、电商平台客户证件照自助打印、培训机构学员照片采集、中小学学籍及毕业照片采集、大学生毕业图像采集、考试报名平台报名照片制作与审核、银行第三代社保卡采集、残联第三代残疾人证办理、退役军人优待证照片采集、社区出入门禁人像采集、智慧食堂人像采集等
除提供稳定的API以外，还提供证件照小程序及APP定制服务，期待与您的合作。点击查看合作案例
点击查看证件照API接口集成演示