# AI Face Swap # Overview Using AI Face Swap for hyper-realistic effect with multiple faces supported.​ Our face swap artificial intelligence supports swapping one or multiple faces. Either for creating funny pictures of faces, or need a professional tool, we've got you covered. ## Integration Guide * How to implement AI Face Swap * Step 1: Obtain credentials * You need a **Client ID (Your API Key)** and **RSA public key (Your Secret Key)** from the [API Console](https://yce.makeupar.com/api-console/en/account-settings/) . * These are used to generate an encrypted ID token for authentication. --- * Step 3: Upload source and reference images 1. Request upload URLs from the API: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/file/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "files": [ { "file_name": "target.jpg", "file_size": 123456, "content_type": "image/jpeg" } ] } ``` 1. The response provides a pre-signed upload URL and a `file_id`. 2. Upload your file with an HTTP PUT request to the given URL. 3. Store the `file_id` for later use. Repeat this for both **target** and **reference** images. --- * Step 4: Pre-process the target image (face detection) 1. Create a pre-process task: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "request_id": 1, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"] }, "actions": [ { "id": 0 } ] } } ``` 1. The API returns a `task_id`. 2. Poll task status at: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID ``` 1. When finished, you receive a list of detected faces with bounding boxes. --- * Step 5: Run the face swap task 1. Define which reference image will substitute each source image The `face_mapping` array defines how faces in the **Source Image** are replaced by faces from the **Reference Images**. It acts as a link list connecting detected faces in the source to specific reference images. * Structure Each element in the array is an object containing two properties: | Parameter | Type | Description | | :--- | :--- | :--- | | `position` | `integer` | The index of the face detected in the **Source Image** (e.g., 0, 1, 2). | | `index` | `integer` | The index of the face image in the **Reference Image List** to swap with. | * Logic Rules 1. **Index Mapping:** The `index` maps directly to the order of images provided in your reference list. * `0`: First Reference Image. * `1`: Second Reference Image. 2. **Skipping Swaps:** To skip swapping a specific face detected in the source, set both `index` and `position` to `-1`. 3. **Array Order:** The order of objects in the array should match based on `position`. * Example Use Case **Scenario:** * **Reference List:** 2 images provided (Image A, Image B). * **Source Image:** Contains 3 faces detected (Face 0, Face 1, Face 2). **Goal:** * Swap **Face 0** (Source) with **Image 1** (Reference). * Skip swapping **Face 1** (Source). * Swap **Face 2** (Source) with **Image 0** (Reference). **Configuration:** ```json "face_mapping": [ { "index": 1, // Use the second reference image "position": 0 // Apply to the first detected face in source }, { "index": -1, // Skip swapping "position": -1 // Skip swapping }, { "index": 0, // Use the first reference image "position": 2 // Apply to the third detected face in source } ] ``` 1. Send the main task request: ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body: ```json { "request_id": 2, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"], "ref_ids": ["REFERENCE_FILE_ID"] }, "actions": [ { "id": 0, "params": { "face_mapping": [ { "index": 0, "position": 0 }, { "index": -1, "position": -1 } ] } } ] } } ``` 1. The response returns a `task_id`. --- * Step 6: Poll task status and retrieve result It’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window. 1. Poll at: ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID ``` 2. When `status` is `success`, the response contains a URL for the generated image. 3. Download or display the image from that URL. --- * Step 7: Integrate into your platform * On a **web frontend**, you can directly implement this with JavaScript using fetch or Axios. * On a **backend** (Node.js, Python, Java, PHP, etc.), you can use the same endpoints with standard HTTP libraries. * Always secure the **client credentials** and perform authentication safely. Avoid embedding private keys directly in client-side code in production. * Implement retry and error handling since the tasks run asynchronously. * Debugging Guide 1. **Invalid TaskId Error**
**Why:** You’ll receive an InvalidTaskId error if you attempt to check the status of a task that has timed out. Therefore, once an AI task is initiated, you’ll need to poll for its status within the polling_interval until the status changes to either success or error.
**Solution:** To avoid the task becoming invalid, it’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window. 2. **Why are some faces not detected in my source image**
**Why:** Reason: The face must be clearly visible, not covered or obstructed, and large enough within the image
**Solution:** Try taking a photo where the face appears larger and is clearly visible without any covering or obstruction --- ## Inputs & Outputs * Real-world examples: Multiple faces swap sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) Single face swap sample: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * Suggestions for How to Shoot: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## File Specs & Errors * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Face Swap|Input and output: the long side must be less than or equal to 4096 pixels|< 10MB|jpg/jpeg/png| * Error Codes | Error Code | Description | | ------------------ | ----------- | | exceed_max_filesize | The input file size exceeds the maximum limit | | invalid_parameter | The parameter value is invalid | | error_download_image | There was an error downloading the source image | | error_download_mask | There was an error downloading the mask image | | error_decode_image | There was an error decoding the source image | | error_decode_mask | There was an error decoding the mask image | | error_download_video | There was an error downloading the source video | | error_decode_video | There was an error decoding the source video | | error_nsfw_content_detected | NSFW content was detected in the source image | | error_no_face | No face was detected in the source image | | error_pose | Failed to detect pose in the source image | | error_face_parsing | Failed to perform face parsing on the source image | | error_inference | An error occurred in the inference pipeline | | exceed_nsfw_retry_limits | Retry limits exceeded to avoid generating NSFW image | | error_upload | There was an error uploading the result image | | error_multiple_people | People count exceeds the maximum limit | | error_no_shoulder | Shoulders are not visible in the source image | | error_large_face_angle | The face angle in the uploaded image is too large | | error_unsupport_ratio | The aspect ratio of the input image is unsupported | | unknown_internal_error | Other internal errors | License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'. Type: http Scheme: bearer ## Download OpenAPI description [AI Face Swap](https://docs.perfectcorp.com/_bundle/reference/ai_face_swap.yaml) ## V1.0 AI Face Swap API allows you to swap faces between a target image and one or more reference images using predefined templates or manual mapping. ### Create a new file. - [POST /s2s/v2.0/file/face-swap](https://docs.perfectcorp.com/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1file~1face-swap/post.md): To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features. ### Run an AI Face Swap face detection task. - [POST /s2s/v2.0/task/face-swap/pre-process](https://docs.perfectcorp.com/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post.md): Use the pre-process task when the source image may contain more than one valid target, or when your integration needs to explicitly choose which detected target receives the effect. For single-target images, pre-process can be skipped when the feature supports a default index value and your application does not need manual target selection. The pre-process task detects candidate targets in the source image and returns their coordinates in data.results.result. Each item in the result array represents one detected target. Review the returned coordinates, map them to the intended face or region in the source image, and use that item's zero-based array index as the index value when creating the effect task. For images with multiple detected faces or regions, do not rely on the default index value without checking the pre-process result. The effect is applied only to the target selected by index, so the integration must confirm the result item that corresponds to the intended target before running the effect task. This task is asynchronous. After creating the task, handle completion with webhook if the feature supports it, or poll the corresponding pre-process status endpoint until data.task_status is success or error. ### Check a AI Face Swap face detection task status. - [GET /s2s/v2.0/task/face-swap/pre-process/{task_id}](https://docs.perfectcorp.com/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1%7Btask_id%7D/get.md) ### Run an AI Face Swap task. - [POST /s2s/v2.0/task/face-swap](https://docs.perfectcorp.com/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post.md): AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details. If webhooks are not supported for the feature, or if your integration cannot use webhooks, implement polling. After starting an AI task, keep polling the task status endpoint at the given polling_interval until the task status is either success or error. Do not stop polling a running task for longer than the allowed polling window. If the task is not polled in time, the task may expire; a later status check can return InvalidTaskId even if processing finished, and the consumed units may still be charged. ### Check a AI Face Swap task status. - [GET /s2s/v2.0/task/face-swap/{task_id}](https://docs.perfectcorp.com/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1%7Btask_id%7D/get.md)