# Run an AI Face Swap task.

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](/develop/webhook) 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`.

Endpoint: POST /s2s/v2.0/task/face-swap
Security: BearerAuthenticationV2

## Security:

  - `BearerAuthenticationV2` (unknown)
    http bearer

## Request fields (application/json):

  - `face_mapping` (array, required)
    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
}
]

  - `face_mapping.index` (integer)
    The index of reference image

  - `face_mapping.position` (integer)
    The index of face on the target image. The index is from faces of detection result.

  - `src_file_url` (string, required)
    Url of the file to run task. The url should be publicly accessible.
    Example: https://example.com/selfie.jpg

  - `ref_file_urls` (array, required)

  - `ref_file_ids` (array, required)

  - `src_file_id` (string, required)
    ID of file to run task. File ID from upload file API.
    Example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=

## Response 200:

  - `200` (unknown)
    Successful execution of the task

## Response 200 fields (application/json):

  - `status` (integer)
    Response status
    Example: 200

  - `data` (object)

  - `data.task_id` (string)
    ID of this task. Task result is valid to query by this ID for 24 hours.
    Example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe

## Response 400:

  - `400` (unknown)
    Failed execution of task

## Response 400 fields (application/json):

  - `status` (integer)
    Response status
    Example: 400

  - `error` (string)
    Error message
    Example: The operation could not be completed

  - `error_code` (string)
    Error code:
* InvalidParameters - Invalid request parameters
* CreditInsufficiency - Insufficient unit to run
* BadRequest - Unexpected request parameter
* InvalidStyleGroup - Invalid style group id
* InvalidStyle - Invalid style id
    Enum: "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest"

## Response 401:

  - `401` (unknown)
    Invalid or missing API key

## Response 401 fields (application/json):

  - `status` (integer)
    Response status
    Example: 401

  - `error` (string)
    Example: Invalid API key

## Response 429:

  - `429` (unknown)
    Too many requests

## Response 429 fields (application/json):

  - `status` (integer)
    Response status
    Example: 429

  - `error` (string)
    Example: Too many requests