AI Retake

Integration Guide

• How to implement AI Retake

  • 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/retake/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/retake/pre-process?task_id=TASK_ID

  1. When finished, you receive a list of detected faces with bounding boxes.

• Step 3: Run the AI Retake 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 the face from the Reference Image. It acts as a link list connecting detected faces in the source to specific reference image.

  Only one face replacement is supported per request. All non-target faces must be set to {"index": -1, "position": -1}. Attempting to replace more than one face will return error_change_too_many_faces. Requests that return this error are not charged. Only the first detected face in the Reference Image is supported, so index must always be 0.

  • Parameters

    Parameter	Type	Description
    position	integer	Index of the detected face in the Source Image (e.g., 0, 1, 2).
    index	integer	Reference face index. Currently, only the first detected face is supported, so this value must be 0.

  • Rules

    • Single Face Replacement: Only one source face can be mapped to a reference face per request.
    • Skip a Face: Set both index and position to -1.
    • Reference Face Index: Only the first detected face in the Reference Image is supported, so index is always 0.

  • Example

    Scenario

    • Reference Image: 1 image containing a single supported face.
    • Source Image: 4 detected faces (Face 0, Face 1, Face 2, Face 3).
    • Goal: Replace Face 2 only and leave Face 0, Face 1 and Face 3 unchanged.
        "face_mapping": [
            {
                "index": -1, // Skip replacing
                "position": -1 // Skip replacing
            },
            {
                "index": -1, // Skip replacing
                "position": -1 // Skip replacing
            },
            {
                "index": 0, // Always use the first reference image
                "position": 2 // Apply to the third detected face in source
            },
            {
                "index": -1, // Skip replacing
                "position": -1 // Skip replacing
            },
        ]

  1. Send the main task request:
  POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake
  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": -1, "position": -1},
              {"index": -1, "position": -1},
              {"index":  0, "position":  2},
              {"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/retake?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. 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:

File Specs & Errors

• Supported Formats & Dimensions

• Error Codes

Unit Consumption