{
  "name": "facefusion",
  "display_name": "人脸融合",
  "description": "介绍如何使用API对人脸融合进行操作，包括人脸融合、选脸融合等。",
  "domain": "other",
  "api_version": "2022-09-27",
  "endpoint": "facefusion.tencentcloudapi.com",
  "actions": [
    {
      "name": "DescribeMaterialList",
      "description": "通常通过腾讯云人脸融合的控制台可以查看到素材相关的参数数据，可以满足使用。本接口返回活动的素材数据，包括素材状态等。用于用户通过Api查看素材相关数据，方便使用。",
      "status": "online",
      "parameters": [
        {
          "name": "ActivityId",
          "type": "string",
          "required": true,
          "description": "活动Id",
          "example": "at_1729474366010862613"
        },
        {
          "name": "MaterialId",
          "type": "string",
          "required": false,
          "description": "素材Id",
          "example": "mt_1597542526641664020_1"
        },
        {
          "name": "Limit",
          "type": "integer",
          "required": false,
          "description": "每次拉取条数。 每次拉取素材最多可支持拉取20条素材信息，如果需要拉取全部素材信息，可以分多次请求拉取全部素材信息。",
          "example": "20"
        },
        {
          "name": "Offset",
          "type": "integer",
          "required": false,
          "description": "偏移量",
          "example": "0"
        }
      ],
      "required": [
        "ActivityId"
      ]
    },
    {
      "name": "FuseFace",
      "description": "本接口用于单脸、多脸、选脸融合，上传人脸图片，得到与素材模板融合后的人脸图片。支持为融合结果图添加标识。查看 融合接入指引。 \u003e - 公共参数中的签名方式必须指定为V3版本，即配置SignatureMethod参数为TC3-HMAC-SHA256。",
      "status": "online",
      "parameters": [
        {
          "name": "ProjectId",
          "type": "string",
          "required": true,
          "description": "活动 ID，请在人脸融合控制台查看。",
          "example": "at_1603326187690926080"
        },
        {
          "name": "ModelId",
          "type": "string",
          "required": true,
          "description": "素材 ID，请在人脸融合控制台查看。",
          "example": "mt_1603586676924403712_1"
        },
        {
          "name": "RspImgType",
          "type": "string",
          "required": true,
          "description": "返回图像方式（url 或 base64) ，二选一。url有效期为7天。",
          "example": "url"
        },
        {
          "name": "MergeInfos",
          "type": "array",
          "required": true,
          "description": "用户人脸图片、素材模板图的人脸位置信息。不能超过6个。 ●图片分辨率限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64，小于4096*4096（单边限制）。 ●图片大小限制：base64 编码后大小不可超过5M， url不超过10M。 ●支持图片格式：支持jpg或png",
          "example": "[{\"Url\":\"https://liudehua-9527.cos.ap-guangzhou.myqcloud.com/image.jpeg\"}]",
          "item_type": "object",
          "children": [
            {
              "name": "Image",
              "type": "string",
              "required": false,
              "description": "输入图片base64。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64。（图片编码之后可能会大30%左右，建议合理控制图片大小）。 ●支持图片格式：支持jpg或png",
              "example": "string"
            },
            {
              "name": "Url",
              "type": "string",
              "required": false,
              "description": "输入图片url。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64。（图片编码之后可能会大30%左右，建议合理控制图片大小）。 ●支持图片格式：支持jpg或png",
              "example": "string"
            },
            {
              "name": "InputImageFaceRect",
              "type": "object",
              "required": false,
              "description": "上传的图片人脸位置信息（人脸框） Width、Height \u003e= 30。",
              "example": "{}",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            },
            {
              "name": "TemplateFaceID",
              "type": "string",
              "required": false,
              "description": "素材人脸ID，不填默认取最大人脸。",
              "example": "string"
            },
            {
              "name": "TemplateFaceRect",
              "type": "object",
              "required": false,
              "description": "模板中人脸位置信息(人脸框)，不填默认取最大人脸。此字段仅适用于图片融合自定义模板素材场景。 Width、Height \u003e= 30。",
              "example": "无",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            }
          ]
        },
        {
          "name": "FuseProfileDegree",
          "type": "integer",
          "required": false,
          "description": "脸型融合比例，数值越高，融合后的脸型越像素材人物。取值范围[0,100] 若此参数不填写，则使用人脸融合控制台中脸型参数数值。（换脸版算法暂不支持此参数调整）",
          "example": "1"
        },
        {
          "name": "FuseFaceDegree",
          "type": "integer",
          "required": false,
          "description": "五官融合比例，数值越高，融合后的五官越像素材人物。取值范围[0,100] 若此参数不填写，则使用人脸融合控制台中五官参数数值。（换脸版算法暂不支持此参数调整）",
          "example": "1"
        },
        {
          "name": "LogoAdd",
          "type": "integer",
          "required": false,
          "description": "为融合结果图添加合成标识的开关，默认为1。 1：添加标识。 0：不添加标识。 其他数值：默认按1处理。 建议您使用显著标识来提示结果图使用了人脸融合技术，是AI合成的图片。",
          "example": "1"
        },
        {
          "name": "LogoParam",
          "type": "object",
          "required": false,
          "description": "标识内容设置。 默认在融合结果图右下角添加“本图片为AI合成图片”字样，您可根据自身需要替换为其他的Logo图片。",
          "example": "{\"LogoUrl\": \"https://cos.ap-guangzhou.myqcloud.com/logo.png\", \"LogoRect\": {\"X\": 10, \"Y\": 10, \"Width\": 20, \"Height\": 20}}",
          "children": [
            {
              "name": "LogoRect",
              "type": "object",
              "required": true,
              "description": "标识图片位于融合结果图中的坐标，将按照坐标对标识图片进行位置和大小的拉伸匹配。 Width、Height \u003c= 2160。",
              "example": "{}",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            },
            {
              "name": "LogoUrl",
              "type": "string",
              "required": false,
              "description": "标识图片Url地址 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●支持图片格式：支持jpg或png 专业版：base64 编码后大小不超过10M。 非专业版：base64 编码后大小不超过5M。",
              "example": "string"
            },
            {
              "name": "LogoImage",
              "type": "string",
              "required": false,
              "description": "输入图片base64。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●支持图片格式：支持jpg或png 专业版：base64 编码后大小不超过10M。 非专业版：base64 编码后大小不超过5M。",
              "example": "string"
            }
          ]
        },
        {
          "name": "FuseParam",
          "type": "object",
          "required": false,
          "description": "融合参数。",
          "example": "{\"ImageCodecParam\":{\"MetaData\": {\"MetaKey\":\"aigc\",\"MetaValue\":\"1\"}}}",
          "children": [
            {
              "name": "ImageCodecParam",
              "type": "object",
              "required": false,
              "description": "图片编码参数",
              "example": "{}",
              "children": [
                {
                  "name": "MetaData",
                  "type": "array",
                  "required": false,
                  "description": "元数据是描述媒体文件的附加信息。通过添加自定义的元数据，可以将一些附加信息嵌入到文件中。这些信息可以用于版权、描述、标识等目的，并在后续的媒体处理或管理过程中使用。 个数不能大于1。",
                  "example": "[]",
                  "item_type": "object",
                  "children": [
                    {
                      "name": "MetaKey",
                      "type": "string",
                      "required": true,
                      "description": "MetaData的Key，字符长度不能超过32",
                      "example": "string"
                    },
                    {
                      "name": "MetaValue",
                      "type": "string",
                      "required": true,
                      "description": "MetaData的Value，字符长度不能超过256",
                      "example": "string"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "required": [
        "ProjectId",
        "ModelId",
        "RspImgType",
        "MergeInfos"
      ]
    },
    {
      "name": "FuseFaceUltra",
      "description": "图片人脸融合（专业版）为同步接口，支持自定义美颜、人脸增强、牙齿增强、拉脸等参数，最高支持8K分辨率，有多个模型类型供选择。查看 融合接入指引。",
      "status": "online",
      "parameters": [
        {
          "name": "RspImgType",
          "type": "string",
          "required": true,
          "description": "返回融合结果图片方式（url 或 base64) ，二选一。url有效期为1天。",
          "example": "url"
        },
        {
          "name": "MergeInfos",
          "type": "array",
          "required": true,
          "description": "用户人脸图片、素材模板图的人脸位置信息。主要用于素材模版中人脸以及用作融合的用户人脸相关信息，两种人脸都需要提供人脸图片，可选择提供人脸框位置，具体见MergeInfo说明 目前最多支持融合模板图片中的6张人脸。",
          "example": "\"MergeInfos\": [{\"Url\": \"https://cos.ap-guangzhou.myqcloud.com/merge.png\"}]",
          "item_type": "object",
          "children": [
            {
              "name": "Image",
              "type": "string",
              "required": false,
              "description": "输入图片base64。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64。（图片编码之后可能会大30%左右，建议合理控制图片大小）。 ●支持图片格式：支持jpg或png",
              "example": "string"
            },
            {
              "name": "Url",
              "type": "string",
              "required": false,
              "description": "输入图片url。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64。（图片编码之后可能会大30%左右，建议合理控制图片大小）。 ●支持图片格式：支持jpg或png",
              "example": "string"
            },
            {
              "name": "InputImageFaceRect",
              "type": "object",
              "required": false,
              "description": "上传的图片人脸位置信息（人脸框） Width、Height \u003e= 30。",
              "example": "{}",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            },
            {
              "name": "TemplateFaceID",
              "type": "string",
              "required": false,
              "description": "素材人脸ID，不填默认取最大人脸。",
              "example": "string"
            },
            {
              "name": "TemplateFaceRect",
              "type": "object",
              "required": false,
              "description": "模板中人脸位置信息(人脸框)，不填默认取最大人脸。此字段仅适用于图片融合自定义模板素材场景。 Width、Height \u003e= 30。",
              "example": "无",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            }
          ]
        },
        {
          "name": "ModelUrl",
          "type": "string",
          "required": false,
          "description": "素材模版图片的url地址。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●图片分辨率限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64，小于8000 * 8000（单边限制）。 ●图片大小限制：base64 编码后大小不可超过10M， url不超过20M。 ●图片格式：支持jpg或png",
          "example": "https://cos.ap-singapore.myqcloud.com/input.png"
        },
        {
          "name": "ModelImage",
          "type": "string",
          "required": false,
          "description": "素材模版图片base64数据。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●素材图片限制：图片中面部尺寸大于34 * 34；图片尺寸大于64 * 64，小于8000*8000（单边限制）。 ●图片大小限制：base64 编码后大小不可超过10M， url不超过20M。 ●支持图片格式：支持jpg或png",
          "example": "/9j/4AAQSkZJRgABAQAAAQABAAD/4gIo...lftXF/DjFZNXoSP5V2U0HMt/1FQf/Z"
        },
        {
          "name": "FusionUltraParam",
          "type": "object",
          "required": false,
          "description": "图片人脸融合（专业版）效果参数。可用于设置拉脸、人脸增强、磨皮、牙齿增强、妆容迁移等融合效果参数，生成理想的融合效果。不传默认使用接口推荐值。具体见FusionUltraParam说明",
          "example": "{\"WarpRadio\": 0.1, \"EnhanceRadio\": 0.8, \"MpRadio\": 0.8, \"TeethEnhanceRadio\": 1, \"MakeupTransferRadio\": 0}",
          "children": [
            {
              "name": "WarpRadio",
              "type": "float",
              "required": false,
              "description": "拉脸强度。主要用于调整生成结果人脸脸型更像素材模板还是用户人脸。取值越大越像用户人脸。 取值范围：0-1之间。默认取值0.7。 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "0.1"
            },
            {
              "name": "EnhanceRadio",
              "type": "float",
              "required": false,
              "description": "人脸增强强度。对整个人脸进行增强，增加清晰度，改善质量。当生成的人脸不够清晰，质感不够好的时候可以设置。取值越大增强强度越大。 取值范围：0-1之间。默认取值0.5。 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "0.8"
            },
            {
              "name": "MpRadio",
              "type": "float",
              "required": false,
              "description": "磨皮强度。当生成脸的图像面部显脏时，可进行设置。 取值范围：0-1之间。默认取值0.5。 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "0.8"
            },
            {
              "name": "BlurRadio",
              "type": "float",
              "required": false,
              "description": "人脸模糊开关（暂不支持） 当生成人脸比较清晰时，将人脸模糊到接近模板的清晰度的程度 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "1"
            },
            {
              "name": "TeethEnhanceRadio",
              "type": "float",
              "required": false,
              "description": "牙齿增强开关，默认取值为1 牙齿增强，修复牙齿。当生成牙齿不好（如牙齿裂开）可以打开此开关 0：牙齿增强关闭 1：牙齿增强打开 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "1"
            },
            {
              "name": "MakeupTransferRadio",
              "type": "float",
              "required": false,
              "description": "妆容迁移开关，默认取值为0。 将素材模板的妆容迁移到融合结果上。即：如果希望妆容效果与模板图保持一致，可以打开此开关。 0：妆容迁移关闭 1：妆容迁移打开 该参数仅对SwapModelType（模型类型）取值1-5生效",
              "example": "0"
            }
          ]
        },
        {
          "name": "LogoAdd",
          "type": "integer",
          "required": false,
          "description": "为融合结果图添加合成标识的开关，默认为1。 1：添加标识。 0：不添加标识。 其他数值：默认按1处理。 建议您使用显著标识来提示结果图使用了人脸融合技术，是AI合成的图片。",
          "example": "1"
        },
        {
          "name": "LogoParam",
          "type": "object",
          "required": false,
          "description": "标识内容设置。 默认在融合结果图右下角添加“本图片为AI合成图片”字样，您可根据自身需要替换为其他的Logo图片。",
          "example": "{\"LogoUrl\": \"https://cos.ap-guangzhou.myqcloud.com/logo.png\", \"LogoRect\": {\"X\": 10, \"Y\": 10, \"Width\": 20, \"Height\": 20}}",
          "children": [
            {
              "name": "LogoRect",
              "type": "object",
              "required": true,
              "description": "标识图片位于融合结果图中的坐标，将按照坐标对标识图片进行位置和大小的拉伸匹配。 Width、Height \u003c= 2160。",
              "example": "{}",
              "children": [
                {
                  "name": "X",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角横坐标。",
                  "example": "1"
                },
                {
                  "name": "Y",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框左上角纵坐标。",
                  "example": "1"
                },
                {
                  "name": "Width",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框宽度。",
                  "example": "30"
                },
                {
                  "name": "Height",
                  "type": "integer",
                  "required": true,
                  "description": "人脸框高度。",
                  "example": "30"
                }
              ]
            },
            {
              "name": "LogoUrl",
              "type": "string",
              "required": false,
              "description": "标识图片Url地址 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●支持图片格式：支持jpg或png 专业版：base64 编码后大小不超过10M。 非专业版：base64 编码后大小不超过5M。",
              "example": "string"
            },
            {
              "name": "LogoImage",
              "type": "string",
              "required": false,
              "description": "输入图片base64。 ●base64 和 url 必须提供一个，如果都提供以 url 为准。 ●支持图片格式：支持jpg或png 专业版：base64 编码后大小不超过10M。 非专业版：base64 编码后大小不超过5M。",
              "example": "string"
            }
          ]
        },
        {
          "name": "SwapModelType",
          "type": "integer",
          "required": false,
          "description": "融合模型类型参数：默认为1。 图片人脸融合（专业版）针对不同场景，提供多种模型供选择。如您的产品是泛娱乐场景，推荐使用1；如您主要用于影像场景，推荐使用4、5。其他模型类型也可以结合您的产品使用场景进行选择，也许会有意想不到的效果 1：默认泛娱乐场景，画面偏锐。 2：影视级场景，画面偏自然。 3：影视级场景，高分辨率，画面偏自然。 4：影视级场景，\ufffd...",
          "example": "1"
        }
      ],
      "required": [
        "RspImgType",
        "MergeInfos"
      ]
    }
  ]
}