> ## Documentation Index
> Fetch the complete documentation index at: https://ailabtools.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Face Swap API

> AI Face Swap API swaps a source face onto a target image and returns an asynchronous task ID for result retrieval.

## Request

* **URL**: `https://www.ailabapi.com/api/portrait/editing/ai-face-swap`
* **Method**: `POST`
* **Content-Type**: `multipart/form-data`

### API Information

| Field                 | Value                                    |
| :-------------------- | :--------------------------------------- |
| API Name              | `AI Face Swap`                           |
| API URL               | `/api/portrait/editing/ai-face-swap`     |
| Documentation URL     | `/docs/ai-portrait/editing/ai-face-swap` |
| Unique Identification | `portrait_ai_face_swap`                  |

### Image requirements

| Field            | Requirements                                                                                               |
| :--------------- | :--------------------------------------------------------------------------------------------------------- |
| `image_target`   | `Image format: JPEG/JPG/PNG`, `Image size: No more than 5 MB.`, `Image resolution: Less than 4096x4096px.` |
| `image_template` | `Image format: JPEG/JPG/PNG`, `Image size: No more than 5 MB.`, `Image resolution: Less than 4096x4096px.` |

### Headers

| Field              | Required | Type     | Description                                           |
| :----------------- | :------- | :------- | :---------------------------------------------------- |
| `ailabapi-api-key` | YES      | `string` | Application API KEY. [Get API KEY](/docs/get-api-key) |

### Body

| Field            | Required | Type   | Description                                                     |
| :--------------- | :------- | :----- | :-------------------------------------------------------------- |
| `image_target`   | YES      | `file` | Target portrait image. The face in this image will be replaced. |
| `image_template` | YES      | `file` | Template portrait image that provides the face to swap.         |

<Tip>
  This API is asynchronous. Submit the request, keep the returned `task_id`, and call [`Querying Async Task Results`](/docs/ai-common/async-task-results/api) to obtain the final image result.
</Tip>

## Response

<Warning>
  **Response Field Handling Flow**

  1. **Handle `Public Response Fields`**

     Parse and validate the `Public Response Fields`, checking the status code or response message to ensure the request is successful and error-free.

  2. **Handle `Business Response Fields`**

     If the `Public Response Fields` are valid and error-free, proceed with processing the business logic in the `Business Response Fields`.
</Warning>

### Public Response Fields

<a href="/docs/response-description" target="_blank">Viewing Public Response Fields and Error Codes</a>

### Business Response Fields

| Field       | Type     | Scope   | Description                                                                                                                                       |
| :---------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `task_type` | `string` | `async` | Task Type. \`\`async`: Asynchronous tasks.`                                                                                                       |
| `task_id`   | `string` |         | Asynchronous task ID. <br />**Please use this field when calling the [Querying Async Task Results](/docs/ai-common/async-task-results/api) API.** |

### Response Example

```json theme={null}
{
  "request_id": "",
  "log_id": "",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_type": "async",
  "task_id": ""
}
```

## `Querying Async Task Results` Response

<Warning>
  **Response Field Handling Flow**

  1. **Handle `Public Response Fields`**

     Parse and validate the `Public Response Fields`, checking the status code or response message to ensure the request is successful and error-free.

  2. **Handle `Business Response Fields`**

     If the `Public Response Fields` are valid and error-free, proceed with processing the business logic in the `Business Response Fields`.
</Warning>

### Public Response Fields

<a href="/docs/response-description" target="_blank">Viewing Public Response Fields and Error Codes</a>

### Business Response Fields

| Field         | Type      | Scope         | Description                                                                                                              |
| :------------ | :-------- | :------------ | :----------------------------------------------------------------------------------------------------------------------- |
| `task_status` | `integer` | `0`, `1`, `2` | Asynchronous task status. ``0`: The task is queued.` ``1`: Asynchronous processing.` \`\`2`: Processing was successful.` |
| `data`        | `object`  |               | The result payload returned by the asynchronous task.                                                                    |
| +`image`      | `string`  |               | Result image URL.                                                                                                        |

<Tip>
  All result URLs are temporarily available and will expire after 24 hours.
</Tip>

### Response Example

```json theme={null}
{
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_status": 2,
  "data": {
    "image": "https://***.jpg"
  }
}
```