Create Video FaceSwap

FaceSwap API can be used to generate convincing videos or images by swapping faces or altering visual elements. This technology can be applied in various fields, such as entertainment, advertising and education.

Upload a Video for FaceSwap

To get started with face swapping, you need to upload a local video file using the upload endpoint. Use the following curl command:

curl -X POST https://upload.heygen.com/v1/asset
     -H 'x-api-key: <your-api-key>'
     --data-binary '@<local file path>'
     -H 'Content-Type: video/mp4'
{
  "code": 100,
  "data": {
    "id": "<id>",
    "name": "<name>",
    "file_type": "video",
    "folder_id": "",
    "meta": null,
    "created_ts": 1696963088
  },
  "msg": null,
  "message": null
}

You only need to specify the content type of the video, which should be video/mp4 for MP4 files or video/webm for WEBM files. The API will respond with an id representing your asset.

File typeContent type
MP4video/mp4
WEBMvideo/webm

Analyze your video

Kick things off by analyzing your base video. You'll need to use the POST method at the following endpoint:‍

curl -XPOST https://api.heygen.com/v1/video/analyze
     -H 'x-api-key:<your-api-key>'
     -d '{"asset_id":"<asset_id>"}'
     -H 'Content-Type: application/json'
{
  "code": 100,
  "data": { "asset_id": "<asset_id>" },
  "msg": "Successfully enqueued analyze video job"
}

In the request body, provide the asset_id of the video you want to analyze. This API call will return a mapping of face IDs to face thumbnails in the video.

Check the Video Analysis Job

See API Reference
Track the progress of your video analysis with a GET call to the following endpoint, using the asset_id of the video in the request body:

curl -X GET https://api.heygen.com/v1/video/analyze.check\?asset_id\=<asset_id> \
     --H 'Accept: application/json' \
     --H 'X-Api-Key: <your-api-key>'
{
  "code": 100,
  "data": {
    "job_status": 2,
    "faces": {
      "8ffdc07614aa4c649cbd6cff85eca7c1": "https://resource.heygen.com/image/8ffdc07614aa4c649cbd6cff85eca7c1/original"
    }
  },
  "msg": "Job complete"
}

Upload a Replacement Face

Now, upload the face you want to swap in using the POST method at this endpoint:

curl -XPOST https://upload.heygen.com/v1/face
     -H 'x-api-key: xxxx'
     --data-binary '@<local_file_path>'
     -H 'Content-Type: image/jpeg'
{
  "code": 100,
  "data": {
    "face_id": "<face_id>",
    "face_url": "<face_url>"
  },
  "msg": null
}

The response will provide you with a unique face_id and the face_url of the uploaded face.

Execute FaceSwap

See API Reference
Once the analysis is complete, proceed to perform the face swap. Use the POST method at this endpoint:

curl -X POST https://api.heygen.com/v1/video/faceswap \
     --H 'Accept: application/json' \
     --H 'X-Api-Key: <your-api-key>'
     --data '{
  "asset_id": "<the asset id>",
  "faceswap_mapping": {
    "<face id in the asset>": "<face id of the uploaded face in the previous step>"
  }
}'
{
  "code": 100,
  "data": { "asset_id": "<asset_id>" },
  "msg": "Successfully enqueued video faceswap job"
}

This API call will provide you with an asset_id for the video that is currently undergoing the face swap.

Check the Video FaceSwap

See API Reference
Lastly, monitor the face swap status with a GET call to this endpoint:

curl --request GET \
     --url https://api.heygen.com/v1/video/faceswap.check\?asset_id\=<asset_id> \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: <your-api-key>'
{
  "code": 100,
  "data": {
    "job_status": 2,
    "video_url": "<video_url>"
  },
  "msg": "Job complete"
}

Include the asset_id of the video in the request body. The response will provide you with the status of the face swap and the URL of the video with the swapped face.

Conclusion

By following the steps outlined in this guide, you can harness the power of the HeyGen Face Swap API to create captivating videos and images by swapping faces and altering visual elements. This technology opens up a world of possibilities for various applications in entertainment, advertising and education.