> ## 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.

# Image Faceswap

> Swap faces in images with high quality

<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.
</Warning>

<Info>
  Experience our face swap technology in action by exploring our interactive demo on GitHub: [AKool Face Swap Demo](https://github.com/AKOOL-Official/akool-face-swap-demo).
</Info>

## Important Notes

* You can get the `opts` parameter (landmarks\_str) through the [Face Detect API](/ai-tools-suite/faceswap/face-detect)
* The Face Detect API returns a `landmarks_str` value that should be used as the value of `opts`
* When using [Face Detect API](/ai-tools-suite/faceswap/face-detect), set `single_face: true` to return only the largest face data, or `false` to return all detected faces
* Ensure that the targetImage and sourceImage arrays are properly aligned and correspond to each other
* **Model Selection**: To use different face swap models available on the official website, set `face_enhance: 0` for **Classic Model**, and `face_enhance: 1` for **HD Optimized** model. For **Clarity Boost** and **Identity Keeper** models, please contact our sales and technical support team


## OpenAPI

````yaml POST /api/open/v3/faceswap/highquality/specifyimage
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/v3/faceswap/highquality/specifyimage:
    post:
      tags:
        - Face Swap
      summary: Image Faceswap
      description: Swap faces in images with high quality
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageFaceswapRequest'
            example:
              targetImage:
                - path: >-
                    https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png
                  opts: 262,175:363,175:313,215:272,279
              sourceImage:
                - path: >-
                    https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png
                  opts: 239,364:386,366:317,472:266,539
              face_enhance: 0
              modifyImage: >-
                https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg
              webhookUrl: ''
      responses:
        '200':
          description: Faceswap request submitted successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/FaceswapResult'
              example:
                code: 1000
                msg: >-
                  Please be patient! If your results are not generated in three
                  hours, please check your input image.
                data:
                  _id: 6593c94c0ef703e8c055e3c8
                  url: >-
                    https://***.cloudfront.net/final_71688047459_.pic-1704184129269-4947-f8abc658-fa82-420f-b1b3-c747d7f18e14-8535.jpg
                  job_id: 20240102082900592-5653
components:
  schemas:
    ImageFaceswapRequest:
      type: object
      required:
        - targetImage
        - sourceImage
        - modifyImage
      properties:
        targetImage:
          type: array
          items:
            $ref: '#/components/schemas/FaceImageWithOpts'
          description: A collection of faces in the original image
        sourceImage:
          type: array
          items:
            $ref: '#/components/schemas/FaceImageWithOpts'
          description: Replacement target image information
        face_enhance:
          type: integer
          enum:
            - 0
            - 1
          default: 0
          description: Whether facial enhancement (1 means open, 0 means close)
        modifyImage:
          type: string
          description: Modify the link address of the image
        webhookUrl:
          type: string
          description: Callback url address based on HTTP request
    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
    FaceswapResult:
      type: object
      properties:
        _id:
          type: string
          description: Interface returns data ID
        url:
          type: string
          description: Faceswap result URL
        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

````