1. API Description
Domain name for API request: facefusion.tencentcloudapi.com.
This API is used to perform the fusion of a single face, multiple faces, and specified faces with the material template by uploading face images. Users can add logos to generated images. See Fusion Access Guide.
- The signature method in the public parameters must be specified as the V3 version. In other words, set the SignatureMethod parameter to TC3-HMAC-SHA256.
We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.
2. Input Parameters
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: FuseFace. |
| Version | Yes | String | Common Params. The value used for this API: 2022-09-27. |
| Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. |
| ProjectId | Yes | String | Activity ID. Check the ID in the Face Fusion console. |
| ModelId | Yes | String | Material ID. Check the ID in the Face Fusion console. |
| RspImgType | Yes | String | Image return method (url or base64). You cannot use both methods at the same time. The URL is valid for 7 days. |
| MergeInfos.N | Yes | Array of MergeInfo | Face position information on the user face image and material template image. No more than 6 entries. |
| LogoAdd | No | Integer | Switch indicating whether to add a synthesis logo to the fusion result image. Default value: 1. 1: add logo 0: do not add logo Other values: add logo It is recommended to use an obvious logo to indicate that the result image uses face fusion technology and is synthesized by AI. |
| LogoParam | No | LogoParam | Logo content settings By default, the text "Synthesized by AI" is added to the bottom right corner of the fusion result image. You can also use other texts. |
| FuseParam | No | FuseParam | Fusion parameter. |
3. Output Parameters
| Parameter Name | Type | Description |
|---|---|---|
| FusedImage | String | When RspImgType is set to url, return the URL (valid for 7 days). When RspImgType is set to base64, return the Base64 code. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
4. Example
Example1 Selecting Face for Fusion
Input Example
POST / HTTP/1.1
Host: facefusion.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: FuseFace
<Common request parameters>
{
"LogoParam": {
"LogoRect": {
"Y": 0,
"X": 0,
"Height": 0,
"Width": 0
},
"LogoUrl": "test1.jpg"
},
"ProjectId": "at_1603326187690926080",
"LogoAdd": 1,
"RspImgType": "url",
"MergeInfos": [
{
"Url": "test.jpg",
"TemplateFaceID": "mt_1603586676924403712_1"
}
],
"ModelId": "mt_1603586676924403712"
}
Output Example
{
"Response": {
"FusedImage": "result.jpg",
"RequestId": "1a2e88a4-3614-48a0-96b9-d09bf6de2fe4"
}
}
5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
Command Line Interface
6. Error Code
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| FailedOperation.BalanceInsufficient | Insufficient balance, failed to open, please recharge and open again. |
| FailedOperation.FaceSizeTooSmall | The face was filtered because it was too small. It is recommended that the face size is not less than 34x34 pixels. |
| FailedOperation.FuseMaterialNotAuth | The material has not been reviewed. |
| FailedOperation.FuseMaterialNotExist | The material does not exist. |
| FailedOperation.ImageDecodeFailed | Image decoding failed. |
| FailedOperation.ImageDownloadError | Image download failed. |
| FailedOperation.ImageResolutionTooSmall | The short edge resolution of the image is lower than 64 pixels. |
| FailedOperation.ImageSizeExceed | The image after Base64 encoding exceeds in size. |
| FailedOperation.ImageSizeInvalid | The image size is too large or too small and does not meet algorithm requirements. |
| FailedOperation.InnerError | Internal service error. |
| FailedOperation.NoFaceDetected | The face cannot be detected because the face box is too small. |
| FailedOperation.ParameterValueError | Parameter or value is invalid. |
| FailedOperation.RequestTimeout | The backend service timed out. |
| FailedOperation.RpcFail | RPC request failed, typically due to algorithm service malfunction. |
| FailedOperation.TemplateFaceIDNotExist | The material face ID does not exist. |
| FailedOperation.UnKnowError | Internal error. |
| FailedOperation.Unknown | Unknown error. |
| InvalidParameterValue.ActivityIdNotFound | Activity ID is not found. |
| InvalidParameterValue.FaceRectParameterValueError | Face box parameters are invalid, or the face box is too small. |
| InvalidParameterValue.MaterialIdNotFound | No material ID is found. |
| InvalidParameterValue.UrlIllegal | The URL format is invalid. |
| RequestLimitExceeded | The number of requests exceeded the rate limit. |
| ResourceInsufficient | Resources are insufficient. |
| ResourceNotFound | The resource does not exist. |
| ResourceUnavailable.Freeze | The account has been frozen. |
| ResourceUnavailable.InArrears | The account is in arrears. |
| ResourceUnavailable.IsOpening | The service is being opened, please wait. |
| ResourceUnavailable.NotExist | The billing status is unknown. Check whether the service has been activated in the console. |
| ResourceUnavailable.Recover | The resource has been possessed. |
| ResourceUnavailable.StopUsing | Services for the account has been stopped. |
Yes
No
Was this page helpful?