> ## Documentation Index > Fetch the complete documentation index at: https://docs.akool.com/llms.txt > Use this file to discover all available pages before exploring further. # Face Swap Plus (Image & Video) > Multi-face swap for images and videos > [!WARNING] > > The resources (image, video, voice) generated by our API are valid for 7 days. > Please save the relevant resources as soon as possible to prevent expiration. > [!TIP] > > Face Swap Plus is a unified API that supports both **image** and **video** face swap. > > * **Single Face Mode**: No pre-detection required, just provide source and target URLs > * **Multi-Face Mode**: Requires [Face Detection API](https://docs.akool.com/ai-tools-suite/face-detection/detect-faces.md) to get `face_url` and `bbox` for each face > * For highest quality image face swap (single face only), use [Face Swap Pro](https://docs.akool.com/ai-tools-suite/faceswap/image-faceswap-v4.md) > * Video Faceswap API is a V3 legacy API. For new projects, we recommend using this API instead ## Features Face Swap Plus supports advanced face swapping scenarios: * **Image and Video**: Unified API for both image and video face swap * **Multi-Face**: Swap multiple faces at once via `face_mapping` * **Single Face Mode**: Use `single_face_mode` for simplified single-face swap * **Style Options**: Choose between `realistic`, `beautify`, or `lossless` styles ## Which API Should I Use? | Scenario | Recommended API | | - | - | | Highest quality image face swap (single face) | [Face Swap Pro](https://docs.akool.com/ai-tools-suite/faceswap/image-faceswap-v4.md) | | Multi-face swap (image/video) | Face Swap Plus ✅ | | Video face swap | Face Swap Plus ✅ (Recommended) | | V3 compatibility required | [Video Faceswap](https://docs.akool.com/ai-tools-suite/faceswap/video-faceswap.md) | ## Parameters ### Core Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `source_url` | string | Yes | Source (new) face image URL | | `target_url` | string | Yes | Target material URL (image or video) | | `webhookUrl` | string | No | Callback URL for result notification | | `face_enhance` | boolean | No | Enable face enhancement (default: false) | | `model_style` | string | No | `realistic` (default), `beautify`, or `lossless` | | `single_face_mode` | boolean | No | `false` (default) for multi-face mode, `true` for single-face mode | ### Multi-Face Mode (default) When `single_face_mode` is `false` (default), use `face_mapping` to define multiple source-target face pairs: | Parameter | Type | Required | Description | | - | - | - | - | | `face_mapping` | array | Yes | Array of face mapping objects | | `face_mapping[].source_face_info` | object | Yes | Source face info | | `face_mapping[].source_face_info.face_url` | string | Yes | Source face image URL | | `face_mapping[].source_face_info.bbox` | number\[] | No | Bounding box `[x1, y1, x2, y2]`. See [bbox rules](#when-is-bbox-required) | | `face_mapping[].target_face_info` | object | Yes | Target face info | | `face_mapping[].target_face_info.face_url` | string | No | Target face image URL | | `face_mapping[].target_face_info.bbox` | number\[] | No | Bounding box `[x1, y1, x2, y2]`. See [bbox rules](#when-is-bbox-required) | ### Single Face Mode When `single_face_mode` is `true`, enables simplified single-face swap mode: | Parameter | Type | Required | Description | | - | - | - | - | | `single_face_mode` | boolean | Yes | Set to `true` for single-face mode | ### When is bbox required? The `bbox` parameter in `source_face_info` and `target_face_info` depends on where `face_url` comes from: | face\_url source | bbox required? | Description | | - | - | - | | `face_urls` from [Face Detection API](https://docs.akool.com/ai-tools-suite/face-detection/detect-faces.md) | **No** | The URL is already a cropped face image, no bbox needed | | User-uploaded original image URL | **Yes** | Provide `bbox` from `crop_region` of the [Face Detection API](https://docs.akool.com/ai-tools-suite/face-detection/detect-faces.md) response | The `crop_region` from Face Detection API returns `[x, y, width, height]`. Convert it to `bbox` format `[x1, y1, x2, y2]`: * `x1 = x`, `y1 = y`, `x2 = x + width`, `y2 = y + height` *** ## Image Face Swap ### Example: Simple Single Face Image Swap ```json theme={null} { "source_url": "https://example.com/new-face.jpg", "target_url": "https://example.com/original.jpg", "single_face_mode": true, "face_enhance": false, "model_style": "realistic" } ``` ### Example: Multi-Face Image Swap with face\_urls (no bbox needed) When using `face_urls` from the Face Detection API response, bbox is not required: ```json theme={null} { "source_url": "https://example.com/new-face.jpg", "target_url": "https://example.com/group-photo.jpg", "model_style": "realistic", "face_enhance": false, "single_face_mode": false, "face_mapping": [ { "source_face_info": { "face_url": "https://example.com/detected-source-face-1.jpg" }, "target_face_info": { "face_url": "https://example.com/detected-target-face-1.jpg" } }, { "source_face_info": { "face_url": "https://example.com/detected-source-face-2.jpg" }, "target_face_info": { "face_url": "https://example.com/detected-target-face-2.jpg" } } ] } ``` ### Example: Multi-Face Image Swap with original URLs (bbox required) When using user-uploaded original image URLs, provide bbox from `crop_region`: ```json theme={null} { "source_url": "https://example.com/new-face.jpg", "target_url": "https://example.com/group-photo.jpg", "model_style": "realistic", "face_enhance": false, "single_face_mode": false, "face_mapping": [ { "source_face_info": { "face_url": "https://example.com/source-original.jpg", "bbox": [120, 80, 280, 320] }, "target_face_info": { "face_url": "https://example.com/target-original.jpg", "bbox": [150, 60, 350, 340] } } ] } ``` *** ## Video Face Swap > [!NOTE] > > Video face swap is an async operation. Use `webhookUrl` or poll the [Get Result API](https://docs.akool.com/ai-tools-suite/faceswap/get-result.md) to check processing status. ### Video Requirements * **Duration**: Keep videos under 60 seconds for optimal processing time * **Format**: MP4, MOV, AVI supported * **Resolution**: Higher resolution videos may take longer to process * **Encoding**: H.264 recommended * **Face Count**: For best results, limit to 8 or fewer faces ### Example: Single Face Video Swap ```json theme={null} { "source_url": "https://example.com/new-face.jpg", "target_url": "https://example.com/video.mp4", "single_face_mode": true, "face_enhance": false, "model_style": "realistic" } ``` ### Example: Multi-Face Video Swap ```json theme={null} { "source_url": "https://example.com/source-face.jpg", "target_url": "https://example.com/group-video.mp4", "single_face_mode": false, "face_enhance": false, "model_style": "realistic", "face_mapping": [ { "source_face_info": { "face_url": "https://example.com/face-1.jpg" }, "target_face_info": { "face_url": "https://example.com/target-face-1.jpg" } }, { "source_face_info": { "face_url": "https://example.com/face-2.jpg" }, "target_face_info": { "face_url": "https://example.com/target-face-2.jpg" } } ] } ``` ### Example: Video Swap with Webhook ```json theme={null} { "source_url": "https://example.com/new-face.jpg", "target_url": "https://example.com/video.mp4", "single_face_mode": true, "webhookUrl": "https://your-server.com/webhook/faceswap-callback", "face_enhance": true, "model_style": "realistic" } ``` *** ## Checking Results After submitting a face swap request, use the [Get Result API](https://docs.akool.com/ai-tools-suite/faceswap/get-result.md) to check the status: | Status | Description | | - | - | | 1 | In Queue - Your request is waiting to be processed | | 2 | Processing - Face swap is currently being generated | | 3 | Success - Face swap completed, result URL is available | | 4 | Failed - Face swap failed, please check your input | ## OpenAPI ````yaml POST /api/open/v4/faceswap/faceswapPlusByImage openapi: 3.0.3 info: title: Face Swap API description: API for face swapping in images and videos version: 1.0.0 servers: - url: https://openapi.akool.com description: Production server security: - ApiKeyAuth: [] - BearerAuth: [] paths: /api/open/v4/faceswap/faceswapPlusByImage: post: tags: - Face Swap summary: Face Swap Plus description: > Face Swap Plus API (`akool_faceswap_classic_plus`) - Multi-face swap for images and videos. - Supports **multiple faces** via `face_mapping` - Supports both **images and videos** (`source_url` / `target_url`) - Supports `single_face_mode` for single-face swap - Supports `model_style` (realistic / beautify / lossless) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageFaceswapPlusRequest' examples: multi_face: summary: Multi-Face Swap value: source_url: https://example.com/new-face.jpg target_url: https://example.com/group-photo.jpg face_enhance: false model_style: realistic single_face_mode: false face_mapping: - source_face_info: face_url: https://example.com/source-face-1.jpg target_face_info: face_url: https://example.com/target-face-1.jpg - source_face_info: face_url: https://example.com/source-face-2.jpg target_face_info: face_url: https://example.com/target-face-2.jpg video_segment: summary: Video Single Face Swap value: source_url: https://example.com/new-face.jpg target_url: https://example.com/video.mp4 single_face_mode: true face_enhance: false responses: '200': description: Faceswap request submitted successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/FaceswapV4Result' example: code: 1000 msg: OK data: _id: 6593c94c0ef703e8c055e3c8 job_id: 20240102082900592-5653 components: schemas: ImageFaceswapPlusRequest: type: object required: - source_url - target_url properties: source_url: type: string description: Source (new) face image URL target_url: type: string description: Target material URL (image or video) webhookUrl: type: string description: Callback URL for result notification face_enhance: type: boolean default: false description: Whether to enable face enhancement (default false) model_style: type: string enum: - realistic - beautify - lossless default: realistic description: 'Model style: `realistic` (default), `beautify`, or `lossless`' face_mapping: type: array items: $ref: '#/components/schemas/FaceMappingItem' description: > Face mapping array for multi-face swap (required when `single_face_mode` is false). Each item maps one source face to one target face. single_face_mode: type: boolean default: false description: > When `true`, enables single-face mode for simplified single-face swap. When `false` (default), uses `face_mapping` for multi-face swap. ApiResponse: type: object required: - code - msg properties: code: type: integer description: 'Interface returns business status code (1000: success)' example: 1000 msg: type: string description: Interface returns status information example: OK FaceswapV4Result: type: object properties: _id: type: string description: Interface returns data ID job_id: type: string description: Task processing unique ID FaceMappingItem: type: object required: - source_face_info - target_face_info properties: source_face_info: type: object required: - face_url properties: face_url: type: string description: > URL of the source (new) face image. Can be a `face_urls` value from the Face Detection API (bbox not needed), or a user-uploaded original image URL (bbox required). bbox: type: array items: type: number minItems: 4 maxItems: 4 description: > Bounding box `[x1, y1, x2, y2]` for the source face (optional). Required when `face_url` is a user-uploaded original image URL. Get this value from the `crop_region` field of the Face Detection API response. Not needed when `face_url` comes from `face_urls` in the Face Detection API response. target_face_info: type: object properties: face_url: type: string description: > URL of the target (original) face image. Can be a `face_urls` value from the Face Detection API (bbox not needed), or a user-uploaded original image URL (bbox required). bbox: type: array items: type: number minItems: 4 maxItems: 4 description: > Bounding box `[x1, y1, x2, y2]` for the target face (optional). Required when `face_url` is a user-uploaded original image URL. Get this value from the `crop_region` field of the Face Detection API response. Not needed when `face_url` comes from `face_urls` in the Face Detection API response. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded. BearerAuth: type: http scheme: bearer description: >- Your API Key used for request authorization. Get Token from authentication/usage#get-the-token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.