Enhance your photo avatar by adding dynamic motion and immersive sound effects! Follow this step-by-step guide to bring your avatar to life.

Add Motion

See detailed API reference
Add motion to your photo avatar by sending a POST request to the API with the avatar's ID.

curl --request POST \
     --url https://api.heygen.com/v2/photo_avatar/add_motion \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your-api-key>' \
     --data '{"id": "62d4489300634c3f99c0ec994c31fa76"}'

{
    "error": null,
    "data": {
        "id": "e08fcc7348ef4f839ed31abf000cef2c"
    }
}

Check Status:
See detailed API reference

curl -L 'https://api.heygen.com/v2/photo_avatar/e08fcc7348ef4f839ed31abf000cef2c' \
-H 'accept: application/json' \
-H 'X-Api-Key: <your-api-key>'

{
    "error": null,
    "data": {
        "id": "e08fcc7348ef4f839ed31abf000cef2c",
        "image_url": "",
        "created_at": 1737665964.0,
        "name": "name",
        "status": "pending",
        "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
        "is_motion": true,
        "motion_preview_url": null,
        "business_type": "generated",
        "upscale_availability": {
            "available": false,
            "reason": "Photo avatar look upload not completed"
        },
        "upscaled": false,
        "background_sound_effect": null
    }
}

{
    "error": null,
    "data": {
        "id": "e08fcc7348ef4f839ed31abf000cef2c",
        "image_url": "https://files2.heygen.ai/avatar/v3/e08fcc7348ef4f839ed31abf000cef2c/full/2.2/raw_preview_image.webp",
        "created_at": 1737665964.0,
        "name": "name",
        "status": "completed",
        "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
        "is_motion": true,
        "motion_preview_url": "https://files2.heygen.ai/avatar/v3/e08fcc7348ef4f839ed31abf000cef2c/full/2.2/preview_video_target.mp4",
        "business_type": "generated",
        "upscale_availability": {
            "available": true,
            "reason": null
        },
        "upscaled": false,
        "background_sound_effect": null
    }
}

Add Sound Effect

See detailed API reference
Add a sound effect to your photo avatar by sending a POST request with the avatar's ID.

curl --request POST \
     --url https://api.heygen.com/v2/photo_avatar/add_sound_effect \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your-api-key>' \
     --data '{"id": "e08fcc7348ef4f839ed31abf000cef2c"}'

{
    "error": null,
    "data": {
        "code": 100,
        "data": {
            "sound_effect_id": "9e283fb2ae25439886f1cf0e5f882fd5"
        },
        "msg": null,
        "message": null
    }
}

Check Status:
See detailed API reference

curl -L 'https://api.heygen.com/v2/photo_avatar/e08fcc7348ef4f839ed31abf000cef2c' \
-H 'accept: application/json' \
-H 'X-Api-Key: <your-api-key>'

{
    "error": null,
    "data": {
        "id": "e08fcc7348ef4f839ed31abf000cef2c",
        "image_url": "https://files2.heygen.ai/avatar/v3/e08fcc7348ef4f839ed31abf000cef2c/full/2.2/raw_preview_image.webp",
        "created_at": 1737665964.0,
        "name": "name",
        "status": "completed",
        "group_id": "0b1b8dabd16f40a2b2ae6599790bba05",
        "is_motion": true,
        "motion_preview_url": "https://files2.heygen.ai/avatar/v3/e08fcc7348ef4f839ed31abf000cef2c/full/2.2/preview_video_target.mp4",
        "business_type": "generated",
        "upscale_availability": {
            "available": true,
            "reason": null
        },
        "upscaled": false,
        "background_sound_effect": {
            "status": "COMPLETED",
            "sound_effect_id": "9e283fb2ae25439886f1cf0e5f882fd5",
            "sound_effect_preview_url": "https://files2.heygen.ai/avatar/v3/e08fcc7348ef4f839ed31abf000cef2c/9e283fb2ae25439886f1cf0e5f882fd5/sound_effect_preview.mp4",
            "file_meta": {
                "id": "9e283fb2ae25439886f1cf0e5f882fd5",
                "size": 353428,
                "duration": 22.0474,
                "status": 2,
                "mime_type": "audio/mpeg",
                "meta": {
                    "audios": {
                        "m4a": "https://resource2.heygen.ai/audio/9e283fb2ae25439886f1cf0e5f882fd5/transcode.m4a",
                        "mp3": "https://resource2.heygen.ai/audio/9e283fb2ae25439886f1cf0e5f882fd5/transcode.mp3",
                        "ogg": "https://resource2.heygen.ai/audio/9e283fb2ae25439886f1cf0e5f882fd5/transcode.ogg",
                        "wav": "https://resource2.heygen.ai/audio/9e283fb2ae25439886f1cf0e5f882fd5/transcode.wav"
                    },
                    "thumbnails": {}
                },
                "properties": null,
                "created_ts": 1737666964
            }
        }
    }
}

Conclusion

By following the steps outlined in this guide, you can easily add dynamic motion and immersive sound effects to your photo avatars, enhancing the user experience and bringing your avatars to life.