Create Videos with Talking Photo

Preset avatars may not suitable if you need to use your own portrait, or when you need more customized portraits. The greatest thing is, you can create your own avatar with just one photo, which we call a "Talking Photo." Here's how to create a talking photo with your own image.

Upload the Talking Photo Image

See detailed API reference
To upload your photo, use the following command with the upload endpoint:

curl -XPOST https://upload.heygen.com/v1/talking_photo
     -H 'x-api-key: <your-api-key>'
     --data-binary '@<local file path>'
     -H 'Content-Type: image/jpeg'
{
  "code": 100,
  "data": {
    "talking_photo_id": "<talking_photo_id>",
    "talking_photo_url": "<talking_photo_url>"
  },
  "msg": null,
  "message": null
}

Make sure your photo meets these requirements:

  • The face is intact and clearly visible.
  • Recommend using real human faces.
  • Only one face shows in the photo.
  • The resolution of the face area is larger than 200x200 pixels.

You only need to specify the content type of the video, which should be image/jpeg for JPEG files or image/png for PNG files.

File typeContent type
JPEGimage/jpeg
PNGimage/png

See detailed API reference
Or you can get your already existing talking photo id with the list endpoint:

curl --request GET \
     --url https://api.heygen.com/v1/talking_photo.list \
     --header 'accept: application/json' \
     --header 'x-api-key: <your-api-key>'
{
  "code": 100,
  "data": [
    {
      "circle_image": "",
      "id": "<id>",
      "image_url": "<image_url>"
    }
    ...
  ],
  "message": "Success"
}

Create a Video with the Talking Photo

See detailed API reference
To generate talking photo videos you need to change "Character Settings" type as talking_photo then you need to provide talking_photo_id you got in the previous step.

curl -X POST https://api.heygen.com/v2/video/generate \
-H 'X-Api-Key: <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "video_inputs": [
    {
      "character": {
        "type": "talking_photo",
        "talking_photo_id": "<talking_photo_id>"
      },
      "voice": {
        "type": "text",
        "input_text": "With HeyGen, it\'s very easy to create talking photo videos.",
        "voice_id": "d7bbcdd6964c47bdaae26decade4a933"
      },
      "background": {
        "type": "color",
        "value": "#FAFAFA"
      }
    }
  ],
  "test": true,
  "aspect_ratio": "16:9"
}'
{
  "code": 100,
  "data": {
    "video_id": "<video_id>"
  },
  "message": "Success"
}