> ## 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 Pro > Highest quality face swap for images 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. ## Face Swap Pro (akool\_faceswap\_image\_hq) Face Swap Pro delivers the highest quality face swap results for images: * **More Realistic**: Advanced algorithm produces natural and lifelike face swaps * **More Similar**: Enhanced matching ensures high similarity to the source face * **Simplified Integration**: `opts` parameter is optional, no face detection step required * **Batch Support**: Supports up to 50 sourceImage / targetImage pairs per request * **Optional Face Landmarks**: Provide `opts` from the [Face Detection API](/ai-tools-suite/face-detection/detect-faces) for improved accuracy ## Parameters | Parameter | Type | Required | Description | | -------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sourceImage` | array | Yes | Source (new) face image URLs. Each item: `{ "path": "url", "opts": "landmarks" }`. Min 1, Max 50 items. | | `sourceImage[].path` | string | Yes | Valid URL of the source face image. Must be a valid HTTP/HTTPS URL. | | `sourceImage[].opts` | string | Conditional | Face landmark string from `crop_landmarks` of [Face Detection API](/ai-tools-suite/face-detection/detect-faces). **Required** when `sourceImage` or `targetImage` array length > 1. **Optional** when both arrays have exactly 1 element. | | `targetImage` | array | Yes | Target face image URLs. Each item: `{ "path": "url", "opts": "landmarks" }`. Min 1, Max 50 items. | | `targetImage[].path` | string | Yes | Valid URL of the target face image. Must be a valid HTTP/HTTPS URL. | | `targetImage[].opts` | string | Conditional | Face landmark string from `crop_landmarks` of [Face Detection API](/ai-tools-suite/face-detection/detect-faces). **Required** when `sourceImage` or `targetImage` array length > 1. **Optional** when both arrays have exactly 1 element. | | `model_name` | string | No | Default: `akool_faceswap_image_hq` | | `webhookUrl` | string | No | Callback URL for result notification | | `face_enhance` | boolean | No | Enable face enhancement (default: false) | | `single_face_mode` | boolean | No | When `true`, enables single face mode (default: false) | ## Getting opts Value The `opts` parameter provides face landmark coordinates for improved face alignment accuracy. To get the `opts` value: 1. Call the [Face Detection API](/ai-tools-suite/face-detection/detect-faces) with your image URL 2. Use the `crop_landmarks` value from the response as the `opts` parameter 3. Format: colon-separated coordinate pairs, e.g. `"262,175:363,175:313,215:272,279"` ## Important Notes ### Parameter Validation Rules * **`path` validation**: Each `path` must be a valid HTTP/HTTPS URL. Invalid URLs will be rejected. * **`opts` conditional requirement**: * When both `sourceImage` and `targetImage` arrays have exactly **1 element each**: `opts` is **optional** for all elements * When either `sourceImage` or `targetImage` array has **more than 1 element**: `opts` is **required** for **every element** in both arrays * If any element is missing `opts` when required, the request will be rejected with a validation error ### Usage Guidelines * For single face swap (1 source + 1 target): `opts` is optional but recommended for better accuracy * For batch face swap (multiple faces): `opts` is required for all elements to ensure proper face mapping * For multi-face swap, image + video support, or video segment swap, use [Face Swap Plus](/ai-tools-suite/faceswap/faceswap-plus) ## Example: Single Face Swap (opts Optional) When both arrays have exactly 1 element, `opts` is optional: ```json theme={null} { "sourceImage": [ { "path": "https://example.com/new-face.jpg" } ], "targetImage": [ { "path": "https://example.com/original.jpg" } ], "model_name": "akool_faceswap_image_hq", "face_enhance": false, "single_face_mode": false } ``` ## Example: Single Face Swap with opts (Recommended) ```json theme={null} { "sourceImage": [ { "path": "https://example.com/new-face.jpg", "opts": "239,364:386,366:317,472:266,539" } ], "targetImage": [ { "path": "https://example.com/original.jpg", "opts": "262,175:363,175:313,215:272,279" } ], "model_name": "akool_faceswap_image_hq", "face_enhance": false, "single_face_mode": false } ``` ## Example: Batch Face Swap (opts Required) When either array has more than 1 element, `opts` is **required** for **all elements**: ```json theme={null} { "sourceImage": [ { "path": "https://example.com/new-face-1.jpg", "opts": "239,364:386,366:317,472:266,539" }, { "path": "https://example.com/new-face-2.jpg", "opts": "150,200:250,200:200,250:180,300" } ], "targetImage": [ { "path": "https://example.com/original.jpg", "opts": "262,175:363,175:313,215:272,279" }, { "path": "https://example.com/original-2.jpg", "opts": "100,150:200,150:150,200:120,250" } ], "model_name": "akool_faceswap_image_hq", "face_enhance": false, "single_face_mode": false } ``` ## OpenAPI ````yaml POST /api/open/v4/faceswap/faceswapByImage 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/faceswapByImage: post: tags: - Face Swap summary: Face Swap Pro description: > 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageFaceswapProRequest' example: sourceImage: - path: https://example.com/new-face.jpg targetImage: - path: https://example.com/original.jpg model_name: akool_faceswap_image_hq 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: ImageFaceswapProRequest: type: object required: - sourceImage - targetImage properties: sourceImage: type: array items: $ref: '#/components/schemas/FaceImageWithOpts' minItems: 1 maxItems: 50 description: > 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). targetImage: type: array items: $ref: '#/components/schemas/FaceImageWithOpts' minItems: 1 maxItems: 50 description: > 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). model_name: type: string enum: - akool_faceswap_image_hq default: akool_faceswap_image_hq description: 'Model name (default: `akool_faceswap_image_hq`)' webhookUrl: type: string description: Callback URL for result notification face_enhance: type: boolean default: false description: Whether to enable face enhancement (default false) single_face_mode: type: boolean default: false description: > When `true`, enables single face mode for simplified single-face swap. When `false` (default), standard mode. 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 FaceImageWithOpts: type: object required: - path properties: path: type: string format: uri description: | Valid URL of the face image. Must be a valid HTTP/HTTPS URL. Invalid URLs will be rejected during validation. opts: type: string description: > 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" 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 ````