---
title: "Face Swap Pro"
method: POST
path: "/api/open/v4/faceswap/faceswapByImage"
tags: ["Face Swap"]
---

# Face Swap Pro

`POST /api/open/v4/faceswap/faceswapByImage`

Face Swap Pro API (`akool_faceswap_image_hq`) - Highest quality face swap for images.

- More realistic, more similar results
- Simplified integration: `opts` parameter is optional when both arrays have 1 element
- Supports up to 50 sourceImage / targetImage pairs
- **Validation Rules**:
  - Each `path` must be a valid HTTP/HTTPS URL
  - `opts` is **required** when either array has more than 1 element
  - `opts` is **optional** when both arrays have exactly 1 element each

## Request body

- ImageFaceswapProRequest
  - `sourceImage` FaceImageWithOpts[], required — Source (new) face image URL array. Each item contains `path` (required, must be valid URL) and `opts` (conditional). **`opts` requirement**: - **Required** when `sourceImage` or `targetImage` array length > 1 (all elements must have `opts`) - **Optional** when both `sourceImage` and `targetImage` arrays have exactly 1 element each The `opts` value comes from the `crop_landmarks` field returned by the [Face Detection API](/ai-tools-suite/face-detection/detect-faces).
    - `path` string, uri, required — Valid URL of the face image. Must be a valid HTTP/HTTPS URL. Invalid URLs will be rejected during validation.
    - `opts` string — Face landmark coordinates string (conditional requirement). You can get this value from the `crop_landmarks` field returned by the [Face Detection API](/ai-tools-suite/face-detection/detect-faces). **Required** when `sourceImage` or `targetImage` array length > 1. **Optional** when both `sourceImage` and `targetImage` arrays have exactly 1 element each. When provided, improves face alignment accuracy. Format: colon-separated coordinate pairs, e.g. "262,175:363,175:313,215:272,279"
  - `targetImage` FaceImageWithOpts[], required — Target face image URL array. Each item contains `path` (required, must be valid URL) and `opts` (conditional). **`opts` requirement**: - **Required** when `sourceImage` or `targetImage` array length > 1 (all elements must have `opts`) - **Optional** when both `sourceImage` and `targetImage` arrays have exactly 1 element each The `opts` value comes from the `crop_landmarks` field returned by the [Face Detection API](/ai-tools-suite/face-detection/detect-faces).
    - `path` string, uri, required — Valid URL of the face image. Must be a valid HTTP/HTTPS URL. Invalid URLs will be rejected during validation.
    - `opts` string — Face landmark coordinates string (conditional requirement). You can get this value from the `crop_landmarks` field returned by the [Face Detection API](/ai-tools-suite/face-detection/detect-faces). **Required** when `sourceImage` or `targetImage` array length > 1. **Optional** when both `sourceImage` and `targetImage` arrays have exactly 1 element each. When provided, improves face alignment accuracy. Format: colon-separated coordinate pairs, e.g. "262,175:363,175:313,215:272,279"
  - `model_name` 'akool_faceswap_image_hq' — Model name (default: `akool_faceswap_image_hq`)
  - `webhookUrl` string — Callback URL for result notification
  - `face_enhance` boolean — Whether to enable face enhancement (default false)
  - `single_face_mode` boolean — When `true`, enables single face mode for simplified single-face swap. When `false` (default), standard mode.

## Response `200`

Faceswap request submitted successfully

- object
  - `code` integer, required — Interface returns business status code (1000: success)
  - `msg` string, required — Interface returns status information
  - `data` FaceswapV4Result
    - `_id` string — Interface returns data ID
    - `job_id` string — Task processing unique ID

---

[API](https://skmtc.dev/akool/apis/face-detection-api.md) · [All operations](https://skmtc.dev/akool/apis/face-detection-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akool/face-detection-api/revisions/ce2ff5679949/schema)