高级证件照API

免费体验

创建高级证件照，支持自定义尺寸、背景色、人脸位置约束、美颜、换装、水印预览和排版输出。适用于证件照规格化、换底、换装、排版等场景。支持异步、同步两种调用方式。

接口返回的链接有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建高级证件照任务

POST /api/tasks/visual/external/idphoto

请求参数

image_file file 可选

图片文件。支持jpg, jpeg, bmp, png, webp, tiff, bitmap。二者必选其一,优先级 image_file>image_url。输入图片小于15MB,分辨率最大4096x4096

图片上传要求请参看使用规范与限制#7。

image_url string 可选

图片下载地址。支持HTTP协议和OSS协议,最长512字符,下载超时10秒

last_id string 可选

复用上次任务输入。任务返回中的image_id(不是任务id),提供则可不传图片输入

sync integer 可选

同步异步。默认值为 0。

0：异步返回任务 ID；
1：同步返回处理结果。

size string 可选

证件照尺寸，默认为原图尺寸。格式为 {width}x{height}，例如 300x400，中间分隔符为小写字母 x；像素值需在 100～2000 之间。

format string 可选

处理后的输出格式。默认值为 png。

png：返回透明背景图片；
jpg：返回白色背景图片。

return_type integer 可选

结果返回形式。默认值为 1。

1：返回图片下载 URL；
2：返回 Base64 字符串。

spec_id integer 可选

规格ID。规格对应证件照的尺寸、背景色、人脸尺寸、文件大小。规格参看使用规范与限制#8。

dpi integer 可选

分辨率dpi。最小值10,最大值1000

px_width integer 可选

像素宽。可传入(px_width, px_height)或(mm_width, mm_height)中的一对值,默认(295, 413),小于1800像素

px_height integer 可选

像素高。与px_width搭配使用,小于1800像素

mm_width integer 可选

毫米宽。与mm_height搭配使用,小于180毫米

mm_height integer 可选

毫米高。与mm_width搭配使用,小于180毫米

change_bg integer 可选

是否抠图换背景。默认值为 1。

0：不更换背景；
1：抠图并更换背景。

bg_color string 可选

背景色。16进制表示,常用颜色: 白色FFFFFF、红色FF0000、蓝色438EDB,默认白色

bg_color2 string 可选

渐变背景色。16进制表示,背景色会从顶部的bg_color渐变到底部的bg_color2,默认为空

face_width integer 可选

脸宽。人脸宽度(像素)

min_face_width integer 可选

最小脸宽。最小人脸宽度(像素)

max_face_width integer 可选

最大脸宽。最大人脸宽度(像素)

face_height integer 可选

脸高。人脸长度(像素)

min_face_height integer 可选

最小脸高。最小人脸长度(像素)

max_face_height integer 可选

最大脸高。最大人脸长度(像素)

head_top integer 可选

头顶距上边。头顶与上边距离(像素)

min_head_top integer 可选

最小头顶距上边。头顶与上边最小距离(像素)

max_head_top integer 可选

最大头顶距上边。头顶与上边最大距离(像素)

chin_top integer 可选

下巴距上边。下巴与上边距离(像素)

min_chin_top integer 可选

最小下巴距上边。下巴与上边最小距离(像素)

max_chin_top integer 可选

最大下巴距上边。下巴与上边最大距离(像素)

eyes_top integer 可选

眼睛距上边。眼睛与上边距离(像素)

min_eyes_top integer 可选

最小眼睛距上边。眼睛与上边最小距离(像素)

max_eyes_top integer 可选

最大眼睛距上边。眼睛与上边最大距离(像素)

auto_bright integer 可选

自动提亮。默认值为 0。

0：关闭自动提亮；
1：开启自动提亮。

bright_factor number 可选

提亮强度。[0, 1],调光系数

auto_smooth integer 可选

自动磨皮。默认值为 0。

0：关闭自动磨皮；
1：开启自动磨皮。

smooth_factor number 可选

磨皮强度。[0, 1],磨皮系数

auto_thin_face integer 可选

自动瘦脸。默认值为 0。

0：关闭自动瘦脸；
1：开启自动瘦脸。

thin_face_factor number 可选

瘦脸强度。[0, 1],瘦脸系数

auto_sharp integer 可选

自动锐化。默认值为 0。

0：关闭自动锐化；
1：开启自动锐化。

sharp_factor number 可选

锐化强度。[0, 1],锐化系数

clothes_id string 可选

服装模板ID。换正装, man_1~man_20, woman_1~woman_20, child_1~child_10,默认为空。服装模板参看使用规范与限制#9。

preview integer 可选

是否仅预览。默认值为 0。

0：返回正式结果；
1：返回带水印的预览图，不消耗算粒。

quality integer 可选

压缩质量。[1, 100],越大生成的证件照文件越大

min_file_size integer 可选

目标最小体积(Bytes)。[0, inf],比如10240表示最小文件大小为10KB,只有当quality为空时起作用,默认为空

max_file_size integer 可选

目标最大体积(Bytes)。[0, inf],只有当quality为空时起作用,默认为空

add_label integer 可选

是否添加标签。默认值为 0。

0：不添加标签；
1：在证件照底部添加标签。

label_text string 可选

标签文案。证件照底部标签内容,默认为空

label_height integer 可选

标签高度。证件照底部标签高度(像素)

layout integer 可选

是否排版。默认值为 0。

0：不返回排版；
1：返回排版结果。

layout_vertical integer 可选

排版方向。默认值为 0。

0：横版排版；
1：竖版排版。

layout_size string 可选

纸张尺寸。默认值为 5inch。

5inch：五寸；
6inch：六寸。

layout_bg_color string 可选

画布背景色。16进制表示,比如: 白色FFFFFF,默认为灰色

layout_qr_code_data string 可选

二维码数据。排版附加二维码数据,默认为空

layout_qr_code_size integer 可选

二维码尺寸。排版附加二维码尺寸像素

layout_label_text string 可选

画布标签文案。排版附加文字,换行用\n表示,默认为空

返回参数

status number

HTTP 响应状态码，详见状态码说明。

200：请求成功；
非 200：请求失败。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

高级证件照任务 ID，用于后续轮询结果。

status number

HTTP 响应状态码，详见状态码说明。

200：请求成功；
非 200：请求失败。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

任务 ID。如果证件照处理失败，请携带此参数联系客服。

data.image_id string

任务返回中的 image_id，不是 task_id。用于下次图片复用，对应输入参数 last_id。

data.created_at integer

任务创建时间戳。

data.processed_at integer

任务开始处理时间戳。

data.completed_at integer

任务完成时间戳。

data.image string

证件照处理结果图片下载 URL 或 base64 数据，URL 结果有效期为 1 小时。

data.progress number

任务处理进度。

100：处理完成。

data.return_type number

结果返回方式。

data.state number

任务处理状态，详见状态码说明。

1：成功；
大于 1：处理中；
小于 0：失败；
-7：无效图片文件。

data.state_detail string

任务处理状态详情。

查询高级证件照结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 60 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/external/idphoto/{task_id}

路径参数

task_id string 必填

创建高级证件照任务后返回的任务 ID，用于查询任务处理结果。

返回参数

status number

HTTP 响应状态码，详见状态码说明。

200：请求成功；
非 200：请求失败。

message string

接口返回消息。任务失败时可参考此字段或联系客服。

data.task_id string

任务 ID。如果证件照处理失败，请携带此参数联系客服。

data.image_id string

任务返回中的 image_id，不是 task_id。用于下次图片复用，对应输入参数 last_id。

data.created_at integer

任务创建时间戳。

data.processed_at integer

任务开始处理时间戳。

data.completed_at integer

任务完成时间戳。

data.image string

证件照处理结果图片下载 URL 或 base64 数据，URL 结果有效期为 1 小时。

data.progress number

任务处理进度。

100：处理完成。

data.return_type number

结果返回方式。

data.state number

任务处理状态，详见状态码说明。

1：成功；
大于 1：处理中；
小于 0：失败；
-7：无效图片文件。

data.state_detail string

任务处理状态详情。

使用规范与限制

接口返回的结果图片链接一般有效期为 1 小时，请及时下载并存储。
HTTP status 为 200 表示 HTTP 请求成功，并非高级证件照制作成功，任务结果请结合 data.state 判断，详见状态码说明。
使用 URL 作为参数传递时，请遵守 URL 编码规范，避免参数解析混乱。
image_file 与 image_url 二者必选其一，且同时传入时优先使用 image_file；也可以通过 last_id 复用上次任务输入，此时可不传图片输入。
普通证件照制作每次消耗 6 算粒；使用 clothes_id 换装每次消耗 15 算粒；启用任一美颜功能额外 +8 算粒；layout=1 额外 +5 算粒；preview=1 带水印预览不消耗算粒。
证件照规格可通过 spec_id 使用预设，也可传入 px_width/px_height 或 mm_width/mm_height；像素值需小于 1800，毫米值需小于 180，dpi 范围为 10~1000。
上传图片需符合以下格式、分辨率和大小限制。

格式分辨率大小

jpg, jpeg, bmp, png, webp, tiff, bitmap 最大 4096x4096 最大15MB

格式	分辨率	大小
jpg, jpeg, bmp, png, webp, tiff, bitmap	最大 4096x4096	最大15MB

证件照规格列表

spec_id	分类	标题	尺寸(mm)	尺寸(px)	DPI	颜色要求
`1101`	通用	小一寸	22x32	260x378	300	无要求
`1102`	通用	一寸	25x35	295x413	300	无要求
`1103`	通用	大一寸	33x48	390x567	300	无要求
`1104`	通用	小二寸	35x45	413x531	300	无要求
`1105`	通用	二寸	35x49	413x579	300	无要求
`1106`	通用	大二寸	35x53	413x626	300	无要求
`1107`	通用	三寸	55x84	649x991	300	无要求
`1108`	通用	四寸	76x102	898x1205	300	无要求
`1109`	通用	五寸	89x127	1051x1500	300	无要求
`2101`	政府	社保卡	26x32	358x441	350	白色
`2102`	政府	身份证	26x32	358x441	350	白色
`2103`	政府	居住证	26x32	358x441	350	白色
`2201`	政府	健康证（一寸）	25x35	295x413	300	蓝色, 白色
`2202`	政府	健康证（小二寸）	35x45	413x531	300	蓝色, 白色
`2203`	政府	医保证	26x32	358x441	300	白色
`2301`	政府	驾驶证、驾照（无回执，小一寸）	22x32	260x378	300	白色
`2401`	政府	退役军人优待证(请不要用于微信小程序，有被下架风险)	30x37	352x440	300	白色
`3101`	签证	巴西签证	40x50	472x590	300	白色
`3102`	签证	冰岛签证	40x50	472x590	300	白色
`3103`	签证	阿根廷签证	40x40	472x472	300	白色
`3105`	签证	韩国签证	35x45	413x531	300	白色
`3106`	签证	肯尼亚签证	50x50	590x590	300	白色
`3107`	签证	马来西亚签证	35x45	413x531	300	白色
`3108`	签证	美国签证	51x51	602x602	300	白色
`3109`	签证	日本签证	45x45	531x531	300	白色
`3110`	签证	世界通用签证	35x45	413x531	300	白色
`3111`	签证	泰国签证	35x45	413x531	300	白色
`3112`	签证	新西兰签证	35x45	413x531	300	白色
`3113`	签证	意大利签证	35x45	413x531	300	白色
`3114`	签证	以色列签证	51x51	602x602	300	白色
`3115`	签证	印度签证	51x51	602x602	300	白色
`3116`	签证	越南签证	35x45	413x531	300	蓝色, 红色, 白色
`3117`	签证	老挝签证	51x51	602x602	300	白色
`3118`	签证	法国签证	35x45	413x531	300	白色
`3119`	签证	缅甸签证	35x45	413x531	300	白色
`3120`	签证	加拿大签证	35x45	413x531	300	白色
`3121`	签证	菲律宾签证	51x51	602x602	300	白色
`3203`	签证	海外申请护照在线预约照片	33x48	389x566	300	白色
`3301`	签证	入台证	35x45	413x531	300	白色
`3302`	签证	港澳通行证	33x48	389x566	300	白色
`4101`	学生	入学照（二寸）	35x49	413x578	300	蓝色, 红色, 白色
`4102`	学生	入学照（一寸）	25x35	295x413	300	蓝色, 红色, 白色
`4103`	入学	香港学生国内报名	40x50	472x590	300	白色
`4201`	学生	全国中小学生学籍照片	26x32	307x378	150	白色
`4301`	学生	大学生图像信息采集	41x54	480x640	300	蓝色
`4401`	学生	毕业照	41x54	480x640	300	蓝色, 白色
`5101`	考试	国家公务员考试（一寸）	25x35	295x413	300	蓝色, 白色
`5130`	考试	国家公务员考试（小二寸）	35x45	413x531	300	蓝色, 白色
`5131`	考试	国家公务员考试（二寸）	35x49	413x579	300	蓝色, 白色
`5102`	考试	安徽公务员考试	25x35	413x531	300	蓝色, 白色
`5103`	考试	北京公务员考试	34x45	401x531	300	蓝色, 白色
`5104`	考试	成都公务员考试	9x11	102x126	300	蓝色, 白色, 红色
`5132`	考试	成都公务员考试	25x35	295x413	300	蓝色, 白色
`5105`	考试	甘肃公务员考试	35x49	413x579	300	蓝色, 白色
`5106`	考试	广西公务员考试	25x35	295x413	300	蓝色, 白色
`5107`	考试	广州公务员考试	35x49	295x413	300	蓝色, 白色
`5108`	考试	贵州公务员考试	18x25	215x300	300	蓝色, 白色, 红色
`5109`	考试	海南公务员考试	35x45	413x531	300	蓝色
`5110`	考试	河北公务员考试	25x35	295x413	300	蓝色, 白色, 红色
`5111`	考试	河南公务员考试	25x35	295x413	300	蓝色, 白色, 红色
`5112`	考试	黑龙江公务员考试	35x45	413x531	300	蓝色, 白色, 红色
`5113`	考试	湖北公务员考试	25x35	295x413	300	蓝色, 白色
`5114`	考试	湖南公务员考试	35x45	413x531	300	蓝色, 白色
`5115`	考试	江苏公务员考试	35x45	413x531	300	蓝色, 白色
`5116`	考试	江西公务员考试	35x45	413x531	300	蓝色, 白色
`5117`	考试	宁夏公务员考试	35x45	413x531	300	蓝色, 白色
`5118`	考试	青海公务员考试	35x45	413x531	300	蓝色, 白色
`5119`	考试	山东公务员考试	35x49	413x579	300	蓝色, 白色, 红色
`5120`	考试	山西公务员考试	25x35	295x413	300	蓝色, 白色, 红色
`5121`	考试	上海公务员考试	13x17	150x200	300	蓝色, 白色
`5122`	考试	陕西公务员考试	35x45	413x531	300	蓝色, 白色
`5123`	考试	深圳公务员考试	35x53	413x626	300	蓝色, 白色, 红色
`5124`	考试	四川公务员考试	25x35	295x413	300	蓝色, 白色
`5125`	考试	西藏公务员考试	25x35	295x413	300	蓝色, 白色
`5126`	考试	新疆公务员考试	35x45	413x531	300	蓝色, 白色
`5127`	考试	云南公务员考试	35x49	413x579	300	蓝色, 白色, 红色
`5128`	考试	山西省省直事业单位考试报名	25x35	295x413	300	白色
`5129`	考试	重庆公务员考试	25x35	295x413	300	蓝色, 白色
`5201`	考试	国考（二寸）	35x45	413x531	300	蓝色, 白色
`5202`	考试	国考（一寸）	25x35	295x413	300	蓝色, 白色
`5203`	考试	甘肃省（国考）	25x35	295x413	300	蓝色, 白色, 红色
`5204`	考试	江西省（国考）	35x53	413x626	300	蓝色, 白色
`5205`	考试	宁夏回族自治区（国考）	35x45	413x531	300	蓝色, 白色
`5206`	考试	青海省（国考）	35x45	413x531	300	蓝色, 白色
`5207`	考试	上海市（国考）	35x53	413x626	300	蓝色
`5301`	考试	成人高考报名	40x54	480x640	300	蓝色
`5302`	考试	成人自考	40x54	480x640	300	蓝色, 白色
`5303`	考试	成人自考	25x34	300x400	300	蓝色, 白色
`5401`	考试	高考报名（一寸）	25x35	295x413	300	蓝色, 白色
`5402`	考试	高考报名（小二寸）	35x45	413x531	300	蓝色, 白色
`5403`	考试	上海中考网报名	14x20	168x240	300	蓝色, 白色, 红色
`5404`	考试	武汉大学研究生考试	13x17	150x200	300	蓝色, 白色, 红色
`5405`	考试	研究生考试	33x48	390x567	300	蓝色, 白色
`5406`	考试	在职研究生考试	35x45	413x531	300	蓝色, 白色
`5501`	考试	普通话水平测试	33x48	390x567	300	蓝色, 白色, 红色
`5502`	考试	商务英语考试	35x49	413x579	300	蓝色, 白色
`5503`	考试	学位英语	33x48	390x567	300	白色
`5504`	考试	英语AB级考试(二寸)	33x48	390x567	300	蓝色
`5505`	考试	英语AB级考试(144X192)	12x16	144x192	300	蓝色, 白色
`5506`	考试	英语三级考试	12x16	295x413	300	蓝色
`5507`	考试	英语四级考试	33x43	390x507	300	蓝色, 白色
`5508`	考试	英语四级考试	12x16	144x192	300	蓝色, 白色
`5509`	考试	英语六级考试	12x16	144x192	300	蓝色, 白色
`5510`	考试	自考学位外语考试	40x54	480x640	300	蓝色
`5601`	考试	证券考试报名	18x25	215x300	300	蓝色, 白色, 红色
`5602`	考试	注册会计师考试（一寸）	25x35	295x413	300	白色
`5603`	考试	注册会计师考试（178x220）	15x19	178x220	300	白色
`5701`	考试	国家医学考试	25x35	295x413	300	蓝色, 白色
`5702`	考试	护士职业资格考试	35x45	413x531	300	白色
`5703`	考试	执业药师资格考试（一寸）	25x35	295x413	300	白色
`5801`	考试	计算机等级考试	12x16	144x192	300	白色
`5802`	考试	青少年电子信息等级考试	35x53	413x626	300	蓝色, 红色
`5803`	考试	青少年机器人技术等级考试	35x53	413x626	300	蓝色, 白色
`5901`	考试	BIM技能等级考试	25x35	295x413	300	白色
`5902`	考试	卫生专业技术资格考试（一寸）	25x35	295x413	300	白色
`5903`	考试	一级注册消防工程师考试	25x35	295x413	300	白色
`5904`	考试	育婴师考试报名（一寸）	25x35	295x413	300	白色
`5905`	考试	国家司法考试	35x53	413x626	300	蓝色, 白色, 红色
`5906`	考试	裁判资格考试	25x35	295x413	300	蓝色
`6101`	资质	二级建造师证（一寸）	25x35	295x413	300	蓝色, 白色
`6102`	资质	二级建造师证（二寸）	35x53	413x626	300	蓝色, 白色
`6103`	资质	一级建造师	25x35	295x413	300	白色
`6201`	资质	导游证（一寸）	25x35	295x413	300	白色
`6202`	资质	导游证（二寸）	35x53	413x626	300	白色
`6302`	资质	职业兽医资格证	19x28	230x334	300	蓝色, 白色
`6303`	资质	职业医师资格证（小二寸）	35x45	413x531	300	白色
`6401`	资质	教师资格证（300x400）	25x34	300x400	300	白色
`6501`	资质	保险职业证（210x270）	18x23	210x270	300	白色
`6502`	资质	会计从业资格证（一寸）	25x35	295x413	300	白色
`6601`	资质	执法证	40x54	480x640	300	白色

换装-服装列表。下载素材zip

分类	服装 ID	图片
男装	man_1
男装	man_2
男装	man_3
男装	man_4
男装	man_5
男装	man_6
男装	man_7
男装	man_8
男装	man_9
男装	man_10
男装	man_11
男装	man_12
男装	man_13
男装	man_14
男装	man_15
男装	man_16
男装	man_17
男装	man_18
男装	man_19
男装	man_20
女装	woman_1
女装	woman_2
女装	woman_3
女装	woman_4
女装	woman_5
女装	woman_6
女装	woman_7
女装	woman_8
女装	woman_9
女装	woman_10
女装	woman_11
女装	woman_12
女装	woman_13
女装	woman_14
女装	woman_15
女装	woman_16
女装	woman_17
女装	woman_18
女装	woman_19
女装	woman_20
童装	child_1
童装	child_2
童装	child_3
童装	child_4
童装	child_5
童装	child_6
童装	child_7
童装	child_8
童装	child_9
童装	child_10

响应

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // 仅在异步轮询结果中存在。
    "processed_at": "1634884056", // 仅在异步轮询结果中存在。
    "completed_at": "1634884056", // 仅在异步轮询结果中存在。
    "image": "https://wxtechsz.oss-cn-shenzhen.aliyuncs.com/tasks/output/visual_external_idphoto/90662b52-deca-42eb-99fa-141289cbd3c1.jpg", // 仅在异步轮询结果中存在。
    "image_id": "19e2bfa2-99c0-11f0-823d-a3b20139f801", // 仅在异步轮询结果中存在。
    "progress": 100, // 仅在异步轮询结果中存在。
    "return_type": 1, // 仅在异步轮询结果中存在。
    "state": 1, // 仅在异步轮询结果中存在。
    "state_detail": "Complete" // 仅在异步轮询结果中存在。
  }
}