{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-reference/ai_face_swap.yaml","sidebar":"sidebar-reference/sidebars.yaml"},"props":{"definitionId":"reference/ai_face_swap.yaml","dynamicMarkdocComponents":[],"baseSlug":"/reference/ai_face_swap","seo":{"title":"AI Face Swap","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"AI Face Swap","description":"# Overview\nUsing 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.\n\n## Integration Guide\n* How to implement AI Face Swap\n   * Step 1: Obtain credentials\n\n        * 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/)\n        .\n        * These are used to generate an encrypted ID token for authentication.\n\n---\n\n   * Step 3: Upload source and reference images\n\n        1. Request upload URLs from the API:\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file/face-swap\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. The response provides a pre-signed upload URL and a `file_id`.\n        2. Upload your file with an HTTP PUT request to the given URL.\n        3. Store the `file_id` for later use. Repeat this for both **target** and **reference** images.\n\n---\n\n   * Step 4: Pre-process the target image (face detection)\n\n        1. Create a pre-process task:\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. The API returns a `task_id`.\n        2. Poll task status at:\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID\n        ```\n        1. When finished, you receive a list of detected faces with bounding boxes.\n\n---\n\n   * Step 5: Run the face swap task\n        1. Define which reference image will substitute each source image\n        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.\n\n                * Structure\n            Each element in the array is an object containing two properties:\n\n            | Parameter | Type | Description |\n            | :--- | :--- | :--- |\n            | `position` | `integer` | The index of the face detected in the **Source Image** (e.g., 0, 1, 2). |\n            | `index` | `integer` | The index of the face image in the **Reference Image List** to swap with. |\n\n                * Logic Rules\n            1.  **Index Mapping:** The `index` maps directly to the order of images provided in your reference list.\n                *   `0`: First Reference Image.\n                *   `1`: Second Reference Image.\n            2.  **Skipping Swaps:** To skip swapping a specific face detected in the source, set both `index` and `position` to `-1`.\n            3.  **Array Order:** The order of objects in the array should match based on `position`.\n\n                * Example Use Case\n\n            **Scenario:**\n            *   **Reference List:** 2 images provided (Image A, Image B).\n            *   **Source Image:** Contains 3 faces detected (Face 0, Face 1, Face 2).\n\n            **Goal:**\n            *   Swap **Face 0** (Source) with **Image 1** (Reference).\n            *   Skip swapping **Face 1** (Source).\n            *   Swap **Face 2** (Source) with **Image 0** (Reference).\n\n            **Configuration:**\n\n            ```json\n            \"face_mapping\": [\n                {\n                    \"index\": 1,  // Use the second reference image\n                    \"position\": 0 // Apply to the first detected face in source\n                },\n                {\n                    \"index\": -1, // Skip swapping\n                    \"position\": -1 // Skip swapping\n                },\n                {\n                    \"index\": 0,  // Use the first reference image\n                    \"position\": 2 // Apply to the third detected face in source\n                }\n            ]\n            ```\n\n        1. Send the main task request:\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body:\n\n        ```json\n        {\n            \"request_id\": 2,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"],\n                \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\": [\n                {\n                \"id\": 0,\n                \"params\": {\n                    \"face_mapping\": [\n                    { \"index\": 0, \"position\": 0 },\n                    { \"index\": -1, \"position\": -1 }\n                    ]\n                }\n                }\n            ]\n            }\n        }\n        ```\n        1. The response returns a `task_id`.\n\n---\n\n   * Step 6: Poll task status and retrieve result\n        It’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window.\n        1. Poll at:\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID\n        ```\n        2. When `status` is `success`, the response contains a URL for the generated image.\n        3. Download or display the image from that URL.\n\n---\n\n   * Step 7: Integrate into your platform\n\n        * On a **web frontend**, you can directly implement this with JavaScript using fetch or Axios.\n        * On a **backend** (Node.js, Python, Java, PHP, etc.), you can use the same endpoints with standard HTTP libraries.\n        * Always secure the **client credentials** and perform authentication safely. Avoid embedding private keys directly in client-side code in production.\n        * Implement retry and error handling since the tasks run asynchronously.\n\n\n        * Debugging Guide\n        1. **Invalid TaskId Error**\n            </br>**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.\n            </br>**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.\n\n        2. **Why are some faces not detected in my source image**\n            </br>**Why:** Reason: The face must be clearly visible, not covered or obstructed, and large enough within the image\n            </br>**Solution:** Try taking a photo where the face appears larger and is clearly visible without any covering or obstruction\n\n---\n\n## Inputs & Outputs\n\n* Real-world examples:\nMultiple faces swap sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg)\n\nSingle face swap sample:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg)\n\n* Suggestions for How to Shoot:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n|  ----  | ----  | ----  | ----  |\n|AI Face Swap|Input and output: the long side must be less than or equal to 4096 pixels|< 10MB|jpg/jpeg/png|\n\n\n* Error Codes\n\n| Error Code | Description |\n| ------------------ | ----------- |\n| exceed_max_filesize | The input file size exceeds the maximum limit |\n| invalid_parameter | The parameter value is invalid |\n| error_download_image | There was an error downloading the source image |\n| error_download_mask | There was an error downloading the mask image |\n| error_decode_image | There was an error decoding the source image |\n| error_decode_mask | There was an error decoding the mask image |\n| error_download_video | There was an error downloading the source video |\n| error_decode_video | There was an error decoding the source video |\n| error_nsfw_content_detected | NSFW content was detected in the source image |\n| error_no_face | No face was detected in the source image |\n| error_pose | Failed to detect pose in the source image |\n| error_face_parsing | Failed to perform face parsing on the source image |\n| error_inference | An error occurred in the inference pipeline |\n| exceed_nsfw_retry_limits | Retry limits exceeded to avoid generating NSFW image |\n| error_upload | There was an error uploading the result image |\n| error_multiple_people | People count exceeds the maximum limit |\n| error_no_shoulder | Shoulders are not visible in the source image |\n| error_large_face_angle | The face angle in the uploaded image is too large |\n| error_unsupport_ratio | The aspect ratio of the input image is unsupported |\n| unknown_internal_error | Other internal errors |\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.22"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/reference/ai_face_swap","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}