人脸融合图片人脸融合专业版-API 文档-文档中心-腾讯云

1. 接口描述

接口请求域名： facefusion.tencentcloudapi.com 。

图片人脸融合（专业版）为同步接口，支持自定义美颜、人脸增强、牙齿增强、拉脸等参数，最高支持8K分辨率，有多个模型类型供选择。查看融合接入指引。
请求频率限制为2次/秒。

推荐使用 API Explorer

点击调试

API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：FuseFaceUltra。
Version	是	String	公共参数，本接口取值：2022-09-27。
Region	是	String	公共参数，详见产品支持的地域列表。
RspImgType	是	String	返回融合结果图片方式（url 或 base64) ，二选一。url有效期为1天。示例值：url
MergeInfos.N	是	Array of MergeInfo	用户人脸图片、素材模板图的人脸位置信息。主要用于素材模版中人脸以及用作融合的用户人脸相关信息，两种人脸都需要提供人脸图片，可选择提供人脸框位置，具体见MergeInfo说明目前最多支持融合模板图片中的6张人脸。示例值："MergeInfos": [{"Url": "https://cos.ap-guangzhou.myqcloud.com/merge.png"}]
ModelUrl	否	String	素材模版图片的url地址。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64，小于8000 * 8000（单边限制）。图片url或者图片 base64 数据，base64 编码后大小不可超过10M（图片编码之后可能会大30%左右，建议合理控制图片大小） ●图片格式：支持jpg或png 示例值：https://cos.ap-singapore.myqcloud.com/input.png
ModelImage	否	String	素材模版图片base64数据。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64，小于8000*8000（单边限制）。图片url或者图片 base64 数据，base64 编码后大小不可超过10M（图片编码之后可能会大30%左右，建议合理控制图片大小） ●支持图片格式：支持jpg或png 示例值：/9j/4AAQSkZJRgABAQAAAQABAAD/4gIo...lftXF/DjFZNXoSP5V2U0HMt/1FQf/Z
FusionUltraParam	否	FusionUltraParam	图片人脸融合（专业版）效果参数。可用于设置拉脸、人脸增强、磨皮、牙齿增强等融合效果参数，生成理想的融合效果。不传默认使用接口推荐值。具体见FusionUltraParam说明示例值：{"WarpRadio": 0.1, "EnhanceRadio": 0.8, "MpRadio": 0.8, "TeethEnhanceRadio": 1}
LogoAdd	否	Integer	为融合结果图添加合成标识的开关，默认为1。 1：添加标识。 0：不添加标识。其他数值：默认按1处理。建议您使用显著标识来提示结果图使用了人脸融合技术，是AI合成的图片。示例值：1
LogoParam	否	LogoParam	标识内容设置。默认在融合结果图右下角添加“本图片为AI合成图片”字样，您可根据自身需要替换为其他的Logo图片。示例值：{"LogoUrl": "https://cos.ap-guangzhou.myqcloud.com/logo.png", "LogoRect": {"X": 10, "Y": 10, "Width": 20, "Height": 20}}
SwapModelType	否	Integer	融合模型类型参数：默认为1。图片人脸融合（专业版）针对不同场景，提供多种模型供选择。如您的产品是泛娱乐场景，推荐使用1；如您主要用于影像场景，推荐使用4、5。其他模型类型也可以结合您的产品使用场景进行选择，也许会有意想不到的效果 1：默认泛娱乐场景，画面偏锐。 2：影视级场景，画面偏自然。 3：影视级场景，高分辨率，画面偏自然。 4：影视级场景，高分辦率，高人脸相似度，画面偏自然，可用于证件照等场景。 5：影视级场景，高分辨率，对闭眼和遮挡更友好。示例值：1

3. 输出参数

参数名称	类型	描述
FusedImage	String	RspImgType 为 url 时，返回结果的 url， RspImgType 为 base64 时返回 base64 数据。url有效期为1天。示例值：https://cos.ap-singapore.myqcloud.com/output.png
RequestId	String	唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 调用失败示例

调用失败示例

输入示例

POST / HTTP/1.1
Host: facefusion.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: FuseFaceUltra
<公共请求参数>

{
    "ModelUrl": "https://cos.ap-guangzhou.myqcloud.com/facefusion/FuseFaceUltra/model.png",
    "RspImgType": "base64",
    "MergeInfos": [
        {
            "Url": "https://cos.ap-guangzhou.myqcloud.com/facefusion/FuseFaceUltra/input.png"
        }
    ],
    "FusionUltraParam": {
        "WarpRadio": 1.2
    }
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "FailedOperation.ParameterValueError",
            "Message": "FusionParam值不合法。"
        },
        "RequestId": "89cdd6c5-cb8f-4cbe-959b-e249f3753f55"
    }
}

示例2 调用成功示例

调用成功示例

输入示例

POST / HTTP/1.1
Host: facefusion.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: FuseFaceUltra
<公共请求参数>

{
    "ModelUrl": "https://cos.ap-guangzhou.myqcloud.com/facefusion/FuseFaceUltra/model.png",
    "RspImgType": "url",
    "MergeInfos": [
        {
            "Url": "https://cos.ap-guangzhou.myqcloud.com/facefusion/FuseFaceUltra/input.png"
        }
    ],
    "FusionUltraParam": {
        "WarpRadio": 0.7
    }
}

输出示例

{
    "Response": {
        "FusedImage": "https://cos.ap-guangzhou.myqcloud.com/facefusion/FuseFaceUltra/output.png",
        "RequestId": "06f9b251-fa48-435e-b391-145d67919b2c"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

Tencent Cloud SDK 3.0 for Python: GitHub Gitee
Tencent Cloud SDK 3.0 for Java: GitHub Gitee
Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
Tencent Cloud SDK 3.0 for Go: GitHub Gitee
Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
Tencent Cloud SDK 3.0 for C++: GitHub Gitee
Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee

命令行工具

Tencent Cloud CLI 3.0

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见公共错误码。

错误码	描述
FailedOperation.BalanceInsufficient	余额不足，开通失败，请充值后再开通。
FailedOperation.FaceSizeTooSmall	人脸因太小被过滤，建议人脸分辨率不小于34*34。
FailedOperation.ImageDecodeFailed	人脸检测-图片解码失败。
FailedOperation.ImageDownloadError	图片下载失败。
FailedOperation.ImagePixelExceed	素材尺寸超过1080*1080像素。
FailedOperation.ImageResolutionTooSmall	图片短边分辨率小于64。
FailedOperation.ImageSizeExceed	输入图片base64数据大小超过5M。
FailedOperation.ImageSizeInvalid	图片尺寸过大或者过小；不满足算法要求。
FailedOperation.InnerError	服务内部错误。
FailedOperation.MediaDataError	素材数据为空。
FailedOperation.ModerationConfigError	审核配置为空。
FailedOperation.ModerationFailed	素材审核失败。
FailedOperation.ModerationResponseError	素材审核结果为空。
FailedOperation.ModerationResultConfigError	审核结果配置为空。
FailedOperation.NoFaceDetected	无法检测出人脸, 人脸框配准分低于阈值。
FailedOperation.ParameterValueError	参数字段或者值有误。
FailedOperation.RequestTimeout	后端服务超时。
FailedOperation.RpcFail	RPC请求失败，一般为算法微服务故障。
FailedOperation.UnKnowError	内部错误。
FailedOperation.Unknown	未知错误。
InvalidParameterValue.FaceRectParameterValueError	人脸框参数有误或者人脸框太小。
InvalidParameterValue.UrlIllegal	URL格式不合法。
RequestLimitExceeded	请求的次数超过了频率限制。
ResourceInsufficient	资源不足。
ResourceNotFound	资源不存在。
ResourceUnavailable.Freeze	账号已被冻结。
ResourceUnavailable.InArrears	账号已欠费。
ResourceUnavailable.IsOpening	服务正在开通中，请稍等。
ResourceUnavailable.NotExist	计费状态未知，请确认是否已在控制台开通服务。
ResourceUnavailable.Recover	资源已被回收。
ResourceUnavailable.StopUsing	账号已停服。