注释事项

快速搞懂怎么传参，返回后怎么判断

上传图片文件，不是图片地址

用表单（multipart/form-data）上传，图片放在 input_image，其它参数一起提交，不要整包发送 JSON，也不要只传图片地址或本地路径

请求时带上密钥

在请求头填写 X-API-Key: 你的密钥，只有证件照规格列表不需要密钥

返回的通常就是图片

成功后直接按图片文件读取，不要当成 JSON 解析，只有图片鉴黄和证件照规格列表返回 JSON

出错时先看报错

先看 HTTP 状态码，200 才是成功，其它状态按失败处理；错误格式和示例见各接口的「失败返回」，别把报错内容当成图片保存

证件照规格列表

获取云平台内置的700多条证件照规格信息

请求 URL

GET/v1/specificationList

入参

该接口无需传入参数

成功返回

HTTP 状态	Content-Type	内容
`200`	`application/json`	返回全部证件照规格，见下方返回示例

返回示例：

jsonc

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "id": 1, // 规格ID
      "name": "一寸", // 规格名称
      "width_px": 295, // 宽度，单位为像素
      "height_px": 413, // 高度，单位为像素
      "width_mm": 25, // 宽度，单位为毫米
      "height_mm": 35, // 高度，单位为毫米
      "icon": 2, // 图标编号，忽略此参数即可
      "category": 1, // 分类编号，1=常用寸照，2=各类签证，3=各类证件
      "dpi": 300 // 图片分辨率
    }
  ]
}

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

生成证件照

传入人像图片，获取透明背景的证件照图片

请求 URL

POST/v1/idphoto

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	单人人像图片，接口按 RGB 三通道图像读取
`height`	`int`	否	`413`	标准证件照高度，单位为像素
`width`	`int`	否	`295`	标准证件照宽度，单位为像素
`human_matting_model`	`str`	否	`ppMattingV2`	人像分割模型，可选：`ppMattingV2`、`hivisionModnet`、`modnetPhotographic`、`rmbg`、`silueta`、`birefnet`
`face_detect_model`	`str`	否	`yunet`	人脸检测模型，可选：`yunet`、`mtcnn`、`retinaface`
`hd`	`bool`	否	`true`	`true` 返回高清照，`false` 返回标准尺寸照片
`dpi`	`int`	否	`300`	输出图片 DPI
`face_align`	`bool`	否	`false`	是否自动矫正头部倾斜
`head_measure_ratio`	`float`	否	`0.2`	人脸面积占照片面积的比例
`head_height_ratio`	`float`	否	`0.45`	人脸中心在照片高度中的位置比例
`top_distance_max`	`float`	否	`0.12`	头顶到照片顶部的最大距离比例
`top_distance_min`	`float`	否	`0.10`	头顶到照片顶部的最小距离比例
`whitening_strength`	`int`	否	`0`	美白强度，`0` 表示不处理
`brightness_strength`	`float`	否	`0`	亮度，`0` 表示不处理
`contrast_strength`	`float`	否	`0`	对比度，`0` 表示不处理
`sharpen_strength`	`float`	否	`0`	锐化强度，`0` 表示不处理
`saturation_strength`	`float`	否	`0`	饱和度，`0` 表示不处理

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回透明背景图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

证件照添加背景

传入透明背景的证件照图片，换成纯色或渐变色背景

请求 URL

POST/v1/add_background

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	透明背景图片
`color`	`str`	否	`#000000`	背景颜色，必须使用完整的 `#RRGGBB` 格式
`dpi`	`int`	否	`300`	输出图片 DPI
`render`	`int`	否	`0`	背景样式：`0` 纯色、`1` 上下渐变、`2` 中心渐变
`kb`	`int`	否	`None`	目标文件大小，单位为 KB；填写后返回 JPEG

成功返回

条件	HTTP 状态	Content-Type	内容
不传入kb	`200`	`image/png`	返回 PNG 图片
传入kb	`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

证件照换装

传入透明背景的证件照图片，进行换装和换底色

请求 URL

POST/v1/change_clothes

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	透明背景图片
`clothes_category`	`int`	否	`0`	服装分类：`0` 不换装、`1` 男装、`2` 女装、`3` 儿童装
`clothes_id`	`int`	否	`0`	服装编号；男装`1～17`，女装`1～17`，儿童装`1～9`。点我下载素材文件
`clothes_face_detect_model`	`str`	是	-	换装人脸检测模型，只支持 `yunet`
`clothes_parsing_model`	`str`	是	-	换装人体解析模型，只支持 `selfieMulticlass`
`color`	`str`	否	`#ffffff`	背景颜色，必须使用完整的 `#RRGGBB` 格式
`dpi`	`int`	否	`300`	输出图片 DPI
`render`	`int`	否	`0`	背景样式：`0` 纯色、`1` 上下渐变、`2` 中心渐变
`kb`	`int`	否	`None`	目标文件大小，单位为 KB；填写后返回 JPEG

成功返回

条件	HTTP 状态	Content-Type	内容
不传入kb	`200`	`image/png`	返回 PNG 图片
传入kb	`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

证件照排版

把证件照排成一整版，方便打印和裁剪

请求 URL

POST/v1/generate_layout_photos

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	已添加背景的证件照，尺寸应与本次传入的 `width × height` 一致
`height`	`int`	否	`413`	单张证件照高度，单位为像素
`width`	`int`	否	`295`	单张证件照宽度，单位为像素
`dpi`	`int`	否	`300`	输出图片 DPI
`layout_size`	`str`	否	`None`	预设画布名称，可选：`six_inch`、`five_inch`、`a4`、`three_r`、`four_r`
`layout_height`	`int`	否	`None`	自定义画布高度，单位为像素，必须与 `layout_width` 同时传入
`layout_width`	`int`	否	`None`	自定义画布宽度，单位为像素，必须与 `layout_height` 同时传入
`crop_line`	`bool`	否	`false`	是否添加裁切线
`kb`	`int`	否	`None`	目标文件大小，单位为 KB

注意：

传入 layout_size 时，不能传入 layout_height 和 layout_width

传入 layout_height 和 layout_width 时，不能传入 layout_size

三项都不传入时，默认使用 six_inch

预设画布尺寸是：

`layout_size`	中文名称	画布尺寸（高度 px × 宽度 px）
`six_inch`	六寸	`1205 × 1795`
`five_inch`	五寸	`1051 × 1500`
`a4`	A4	`2479 × 3508`
`three_r`	3R	`1051 × 1500`
`four_r`	4R	`1205 × 1795`

成功返回

条件	HTTP 状态	Content-Type	内容
不传入kb	`200`	`image/png`	返回 PNG 图片
传入kb	`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

生成模板照

传入人像图片，根据指定模板生成个性化图片

请求 URL

POST/v1/generate_template_photos

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	单人人像图片，接口按 RGB 三通道图像读取
`height`	`int`	否	`413`	模板内证件照高度，单位为像素
`width`	`int`	否	`295`	模板内证件照宽度，单位为像素
`human_matting_model`	`str`	否	`ppMattingV2`	人像分割模型，可选：`ppMattingV2`、`hivisionModnet`、`modnetPhotographic`、`rmbg`、`silueta`、`birefnet`
`face_detect_model`	`str`	否	`yunet`	人脸检测模型，可选：`yunet`、`mtcnn`、`retinaface`
`face_align`	`bool`	否	`true`	是否自动矫正头部倾斜
`template_name`	`str`	否	`template_1`	模板名称，可选：`template_1`、`template_2`
`color`	`str`	否	`#438edb`	模板内证件照的背景颜色，必须使用完整的 `#RRGGBB` 格式
`dpi`	`int`	否	`300`	输出图片 DPI
`kb`	`int`	否	`None`	目标文件大小，单位为 KB

成功返回

条件	HTTP 状态	Content-Type	内容
不传入kb	`200`	`image/png`	返回 PNG 图片
传入kb	`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

情侣红底照

传入双人合照，制作情侣红底照

请求 URL

POST/v1/couple_red_photo

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	必须包含两个人的原始照片
`color`	`str`	否	`#5C1117`	`#5C1117`生成酒红渐变背景，也可选择`#D9001B`、`#D12C25`、`#FF2121`、`#FF0000`、`#FF4C00`、`#9D2933`、`#ED333D`纯色背景
`human_matting_model`	`str`	否	`ppMattingV2`	人像分割模型，可选：`ppMattingV2`、`hivisionModnet`、`modnetPhotographic`、`rmbg`、`silueta`、`birefnet`
`face_detect_model`	`str`	否	`yunet`	人脸检测模型，可选：`yunet`、`mtcnn`、`retinaface`
`dpi`	`int`	否	`300`	输出图片 DPI

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回保持原图宽高的情侣红底照

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

生成美式证件照

传入人像图片，制作美式证件照

请求 URL

POST/v1/american_idphoto

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	单人人像图片，接口按 RGB 三通道图像读取
`height`	`int`	否	`600`	输出图片高度，单位为像素
`width`	`int`	否	`600`	输出图片宽度，单位为像素
`human_matting_model`	`str`	否	`ppMattingV2`	人像分割模型，可选：`ppMattingV2`、`hivisionModnet`、`modnetPhotographic`、`rmbg`、`silueta`、`birefnet`
`face_detect_model`	`str`	否	`yunet`	人脸检测模型，可选：`yunet`、`mtcnn`、`retinaface`
`face_align`	`bool`	否	`true`	是否自动矫正头部倾斜
`background_image`	`UploadFile`	否	`None`	自定义背景图片，上传后优先使用
`background`	`str`	否	`american`	内置背景，目前支持传入 `american`
`dpi`	`int`	否	`300`	输出图片 DPI
`kb`	`int`	否	`None`	目标文件大小，单位为 KB

成功返回

条件	HTTP 状态	Content-Type	内容
不传入kb	`200`	`image/png`	返回 PNG 图片
传入kb	`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片鉴黄

识别图片中的色情、性感等内容，并给出对应评分

请求 URL

POST/v1/checkImg

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待检测图片，接口按 RGB 三通道图像读取

成功返回

HTTP 状态	Content-Type	内容
`200`	`application/json`	返回五项图片分类分数，见下方返回示例

返回示例：

jsonc

{
  "code": 200,
  "msg": "检测成功",
  "data": {
    "drawings": 0.001, // 绘画分数，0～1
    "hentai": 0.002, // 色情动漫分数，0～1
    "neutral": 0.995, // 中性分数，0～1
    "porn": 0.001, // 色情分数，0～1
    "sexy": 0.001 // 性感分数，0～1
  }
}

如何判断是否违规？

使用 porn + hentai >= 0.6 时判定违规即可

注意：

两项分数之和的范围是 0～1
经过测试，0.6 可以通过微信小程序的安全审核

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片抠图

去掉图片背景，只留下人物或物品

请求 URL

POST/v1/human_matting

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待抠图图片，接口按 RGB 三通道图像读取
`human_matting_model`	`str`	否	`ppMattingV2`	分割模型，可选：`ppMattingV2`、`hivisionModnet`、`modnetPhotographic`、`rmbg`、`silueta`、`birefnet`
`dpi`	`int`	否	`300`	输出图片 DPI

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回透明背景抠图；大图会等比例缩小到最长边 `2000px`

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片添加水印

给图片加上文字水印，可以选择居中显示或铺满整张图片

请求 URL

POST/v1/watermark

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待添加水印的图片，支持灰度、RGB 和 RGBA 图像
`text`	`str`	是	-	水印文字
`style`	`str`	否	`striped`	水印样式：`striped` 平铺、`central` 居中
`angle`	`int`	否	`30`	水印旋转角度
`color`	`str`	否	`#171717`	水印颜色，必须使用完整的 `#RRGGBB` 格式
`opacity`	`float`	否	`0.30`	水印不透明度，建议使用 `0～1`
`size`	`int`	否	`40`	水印基准字号，会根据图片大小缩放
`space`	`int`	否	`120`	平铺水印基准间距，会根据图片大小缩放
`dpi`	`int`	否	`300`	输出图片 DPI
`kb`	`int`	否	`None`	目标文件大小，单位为 KB；填写后返回 JPEG

成功返回

条件	HTTP 状态	Content-Type	说明
不传入kb	`200`	`image/png`	返回 PNG 图片，保留透明通道
传入kb	`200`	`image/jpeg`	返回 JPEG 图片，不保留透明通道

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片 KB 压缩

传入图片，压缩到指定大小

请求 URL

POST/v1/set_kb

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待压缩图片，接口按 RGB 三通道图像读取
`dpi`	`int`	否	`300`	输出图片 DPI
`kb`	`int`	否	`50`	目标文件大小，单位为 KB，必须大于 `0`

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/jpeg`	返回 JPEG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片转换格式

传入图片，转成指定格式

请求 URL

POST/v1/convert_image_format

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待转换图片
`target_format`	`str`	是	-	目标格式，可选：`jpg`、`jpeg`、`png`、`gif`

成功返回

条件	HTTP 状态	Content-Type	内容
`target_format` 为 `jpg` 或 `jpeg`时	`200`	`image/jpeg`	返回 JPEG 图片，不保留透明通道
`target_format` 为 `png`时	`200`	`image/png`	返回 PNG 图片，保留透明通道
`target_format` 为 `gif`时	`200`	`image/gif`	返回静态单帧 GIF 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

图片转动漫风

传入图片，制作动漫风格图片

请求 URL

POST/v1/cartoon

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待处理图片，接口按 RGB 三通道图像读取
`cartoon_model`	`str`	否	`cartoon`	动漫风模型，目前支持 `cartoon`

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回 PNG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

黑白照片上色

传入黑白图片或老照片，生成修复并上色后的图片

请求 URL

POST/v1/colourizeImg

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	待上色图片，接口按 RGB 三通道图像读取
`colourize_model`	`str`	否	`ddcolor`	黑白照片上色模型，目前支持 `ddcolor`
`dpi`	`int`	否	`300`	输出图片 DPI

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回 PNG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`

模糊图片变清晰

传入模糊图片，制作高清化图片

请求 URL

POST/v1/deblur

请求头：X-API-Key: 你的密钥

入参

参数	类型	必填	默认值	说明
`input_image`	`UploadFile`	是	-	模糊或低清图片，接口按 RGB 三通道图像读取
`deblur_model`	`str`	否	`realEsrgan`	图片清晰度增强模型，目前支持 `realEsrgan`
`dpi`	`int`	否	`300`	输出图片 DPI

成功返回

HTTP 状态	Content-Type	内容
`200`	`image/png`	返回 PNG 图片

失败返回

HTTP 状态	Content-Type	内容
`404`	`application/json`	`{ "code": 404, "msg": "失败原因" }`