AI Face Swap

Integration Guide

• How to implement AI Face Swap

  • Step 1: Upload source and reference images

    1. Request upload URLs from the API:
    POST https://yce-api-01.makeupar.com/s2s/v2.0/file
    Authorization: Bearer YOUR_API_KEY
    Content-Type: application/json

    Body:

    {
        "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.

    4. Upload the actual file to the upload URL.

• Step 2: Pre-process the source and reference images (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:

  {
      "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 3: 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:

    "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:

  {
      "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 4: 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 5: 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.
  • 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:

Single face swap sample:

• Suggestions for How to Shoot:

File Specs & Errors

• Supported Formats & Dimensions

• Error Codes

Unit Consumption