文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>API 文档>数据处理接口>AI 内容识别>人脸识别>人脸特效

人脸特效

最近更新时间：2025-08-29 15:03:52

我的收藏

本页目录：

功能描述

人脸特效，提供人脸美颜、人像变换、人像分割功能。
注意：
本接口属于 GET 请求，为同步请求方式，需携带签名，具体签名设置请参见 请求签名。

授权说明

通过子账号使用时，需要在 授权策略 的 action 中添加 ci:CreateFaceEffectJob 权限。数据万象支持的所有操作接口请参见 CI action。

服务开通

使用该功能需提前 绑定存储桶，开通数据万象服务。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。

使用限制

使用该接口时，请先确认相关限制条件。详情请参见 使用限制。

费用说明

该接口为付费服务，产生的费用将由数据万象收取，详细计费说明可参见 内容识别费用。


请求

请求示例

原图存储在COS：
GET /<ObjectKey>?ci-process=face-effect&type=<type> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
原图来自其他链接：
GET /?ci-process=face-effect&type=<type>&detect-url=<detect-url> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
注意：
Authorization: Auth String ，详情请参见 请求签名 文档。

请求参数

参数名称
描述
类型
是否必选
ObjectKey
对象文件名，例如 folder/document.pdf
String
必须与参数 detect-url 二选一
ci-process
万象处理能力，人脸特效固定为 face-effect
String
是
detect-url
您可以通过填写 detect-url 处理任意公网可访问的图片链接。不填写 detect-url 时，后台会默认处理 ObjectKey ，填写了 detect-url 时，后台会处理 detect-url 链接，无需再填写 ObjectKey。
detect-url 示例：http://www.example.com/abc.jpg ，需要进行 UrlEncode，处理后为http%3A%2F%2Fwww.example.com%2Fabc.jpg。
String
必须与参数 ObjectKey 二选一
type
人脸特效类型，人脸美颜：face-beautify；人脸性别转换：face-gender-transformation；人脸年龄变化：face-age-transformation；人像分割：face-segmentation
String
是
whitening
type 为 face-beautify 时生效，美白程度，取值范围[0,100]。0不美白，100代表最高程度。默认值30
Integer
否
smoothing
type 为 face-beautify 时生效，磨皮程度，取值范围[0,100]。0不磨皮，100代表最高程度。默认值10
Integer
否
faceLifting
type 为 face-beautify 时生效，瘦脸程度，取值范围[0,100]。0不瘦脸，100代表最高程度。默认值70
Integer
否
eyeEnlarging
type 为 face-beautify 时生效，大眼程度，取值范围[0,100]。0不大眼，100代表最高程度。默认值70
Integer
否
gender
type 为 face-gender-transformation 时生效，选择转换方向，0：男变女，1：女变男。无默认值。限制：仅对图片中面积最大的人脸进行转换。
Integer
否
age
type 为 face-age-transformation 时生效，变化到的人脸年龄，取值范围为[10, 80]。无默认值。限制：仅对图片中面积最大的人脸进行转换。
Integer
否

请求头

公共头部
该请求操作的实现使用公共请求头，了解公共请求头详情请参阅 公共请求头部 文档。
非公共头部
该请求操作无特殊的请求头部信息。

请求体

该请求无请求体。

响应

响应头

公共响应头
该响应包含公共响应头，了解公共响应头详情请参阅 公共响应头部 文档。
特有响应头
该响应无特殊的响应头。

响应体

该响应体返回为 application/xml 数据，包含完整节点数据的内容展示如下：
<Response>
  <ResultImage>
    base64编码的图片
  </ResultImage>
  <ResultMask>
    base64编码的文件
  </ResultMask>
</Response>
具体的数据内容如下：
节点名称（关键字）
父节点
描述
类型
Response
无
保存结果的容器
Container
Response 的内容：
节点名称（关键字）
父节点
描述
类型
ResultImage
Response
处理后的图片 Base64数据
String
ResultMask
Response
人像分割输出参数，一个通过 Base64编码的文件，解码后文件由 Float 型浮点数组成。这些浮点数代表原图从左上角开始的每一行的每一个像素点，每一个浮点数的值是原图相应像素点位于人体轮廓内的置信度（0 - 1）转化的灰度值（0 - 255）
String

错误码

常见的错误信息请参阅 错误码 文档。

实际案例

请求

GET /test.jpg?ci-process=face-effect&type=face-beautify&whitening=70&smoothing=80&faceLifting=70&eyeEnlarging=70 HTTP/1.1
Authorization:q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************
Host:bucket-1250000000.cos.ap-beijing.myqcloud.com

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 414641
Date: Thu, 15 Jun 2017 12:37:29 GMT
Server: tencent-image
x-cos-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhfMjc=

<Response>
  <ResultImage>
    base64编码的图片
  </ResultImage>
</Response>

中国站
目录