Skip to content
AI Face Swap/
/
Run an AI Face Swap task.

Run an AI Face Swap task.

Request

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 or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is success or error.

Security
BearerAuthenticationV2
Bodyapplication/jsonrequired
Any of:
face_mappingArray of objectsrequired

The designated ref image id and face position information to be swapped for each detected face on target image.

Logic Rules

  1. Index Mapping: The index maps directly to the order of images provided in your reference list.
  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 } ]

src_file_urlstringrequired

Url of the file to run task. The url should be publicly accessible.

Example:"https://example.com/selfie.jpg"
ref_file_urlsArray of strings, non-emptyrequired
POST
/s2s/v2.0/task/face-swap
curl -i -X POST \
  https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "src_file_url": "https://example.com/selfie.jpg",
    "ref_file_urls": [
      "https://example.com/accessory.jpg"
    ],
    "face_mapping": [
      {
        "index": 0,
        "position": 0
      }
    ]
  }'

Responses

Successful execution of the task

Bodyapplication/json
statusinteger

Response status

Example:200
dataobject
Response
{
  "status": 200,
  "data": {
    "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
  }
}