高级证件照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 可选

同步异步。1=同步, 0=异步

size string 可选

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

format string 可选

处理后的输出格式,默认值为 png。png 表示透明背景;jpg 表示白色背景。

return_type integer 可选

结果返回形式。1 表示返回图片下载 URL;2 表示返回 base64 字符串。默认值为 1。

spec_id integer 可选

规格ID。规格对应证件照的尺寸、背景色、人脸尺寸、文件大小

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 可选

是否抠图换背景。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或1,是否自动调光

bright_factor number 可选

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

auto_smooth integer 可选

自动磨皮。0或1,是否自动磨皮

smooth_factor number 可选

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

auto_thin_face integer 可选

自动瘦脸。0或1,是否自动瘦脸

thin_face_factor number 可选

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

auto_sharp integer 可选

自动锐化。0或1,是否自动锐化

sharp_factor number 可选

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

clothes_id string 可选

服装模板ID。换正装, man_1~man_20, woman_1~woman_20, child_1~child_10,默认为空

preview integer 可选

是否仅预览。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或1,是否在证件照底部加标签

label_text string 可选

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

label_height integer 可选

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

layout integer 可选

是否排版。0或1,是否返回排版

layout_vertical integer 可选

排版方向。0或1,返回横版或竖版排版,默认为横版

layout_size string 可选

纸张尺寸。"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. 接口返回的结果图片链接一般有效期为 1 小时,请及时下载并存储。

  2. HTTP status 为 200 表示 HTTP 请求成功,并非高级证件照制作成功,任务结果请结合 data.state 判断,详见 状态码说明

  3. 使用 URL 作为参数传递时,请遵守 URL 编码规范,避免参数解析混乱。

  4. image_file 与 image_url 二者必选其一,且同时传入时优先使用 image_file;也可以通过 last_id 复用上次任务输入,此时可不传图片输入。

  5. 普通证件照制作每次消耗 6 算粒;使用 clothes_id 换装每次消耗 15 算粒;启用任一美颜功能额外 +8 算粒;layout=1 额外 +5 算粒;preview=1 带水印预览不消耗算粒。

  6. 证件照规格可通过 spec_id 使用预设,也可传入 px_width/px_height 或 mm_width/mm_height;像素值需小于 1800,毫米值需小于 180,dpi 范围为 10~1000。

  7. 上传图片需符合以下格式、分辨率和大小限制。

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