When uploading footage to create your Video Avatar, we strive to provide clear, easy-to-follow instructions on the walk-through screens. However, sometimes issues with the footage can arise, and you may encounter error messages after the process is complete. If you're wondering "Why was my avatar rejected?" or "Why did my avatar fail?", we've got you covered. Additionally, if your avatar was created but now it's showing an error or has been rejected by moderation, you can find more information here to help you understand the error messages and how to fix your video for the best possible results before re-uploading.
As a general guideline, avoid using footage with
Noticeable cuts - the engine needs one continuous video footage to create the best avatar
Exaggerated head, hand, or shoulder movements, as they may show up in unexpected ways in the final avatar.
You can also review our detailed guidelines for creating a video avatar here.
šļø Creating Digital Twins or Avatars through the API?
Weāve added the relevant API-specific error codes/messages under the matching sections below where applicable. Use the error message returned in your API response to find the matching code, understand what went wrong, and follow the suggested fix before trying again.
Consent Errors
āFootage does not match consentā
API Error Code: Instant avatar consent identity match failed
What this means: Thereās a mismatch between the footage you recorded for your avatar and your consent video. This could happen if it's not the same person in both videos or if the consent video was recorded in a poorly lit environment, making it difficult to verify that itās the same person. Additionally, using a low-quality camera for the consent video may also cause this issue.
ā
Next steps: Youāll need to create a new avatar, ensuring that:
The same person appears in both the consent video and the avatar footage.
The consent video is recorded with a decent camera in a well-lit environment.
āNo face detected in consent footageā
What this means: The system couldn't detect a face in your consent footage.
Next steps: Please ensure your face is clearly visible and follow these guidelines.
āNo valid audio detected in consent footageā
API Error Code: Consent video missing audio
What this means: We couldnāt detect clear audio in the consent video you provided. This usually happens if your microphone was off during recording, or if your webcam microphone wasnāt properly set up.
Next steps: Youāll need to restart the process. When recording your consent video, make sure your microphone is enabled and allowed to work in your browser (we recommend using Google Chrome). This may be due to a permissions issue, so check your browser settings to ensure your microphone is correctly set up.
āCode incorrect or not detected in consent footageā
What this means: At the end of each consent video, you're asked to read a four-letter code to verify the video isn't pre-recorded. If you encounter an error related to reading the code or verification, try the following steps.
Next steps:Ā
Try reading the entire paragraph and code a bit fasterāthough it may sound counterintuitive, it often helps!
Ensure you're reading each letter separately (A-B-C-D) instead of all together.
āļøConsent validation failedāļø
What this means: There was an issue validating your consent video. This can happen if the consent script wasn't read clearly, your face wasn't stable or visible throughout the recording, the video was too long, the audio wasn't synchronized, or an AI-generated avatar was used in the consent video.
āNext steps: Re-record your consent video, ensuring that:
You follow the consent script and read it clearly
Your face is stable and visible throughout the recording
The video is under 35 seconds
The audio is synchronized with the video
You don't use AI-generated content in the consent video
āļøConsent video duration is too longāļø
What this means: Your consent video exceeds the maximum allowed length.
ā
āNext steps: Re-record your consent video. It must be 35 seconds or less.
āļøInstant avatar consent identity match failedāļø
What this means: The system couldn't verify that the same person appears in both the consent video and the avatar footage. This can happen if the lighting or camera quality differs significantly between the two recordings.
ā
āNext steps: Re-record both videos ensuring:
The same person appears in both the consent video and avatar footage
Both videos are recorded in good lighting with decent camera quality
ā
Avatar Footage Errors
āNo human face detected in your avatar footageā
API Error: Missing faces
What this means: The system couldnāt detect a human face in your footage. This might be due to blurry or dark video, or because youāre trying to create an avatar for a character that does not have recognizable human features [eyes, mouth, etc]. Our algorithm doesnāt support avatars without human-like features, so certain avatars will be rejected due to the inability of the technology to locate these features. For 3D models, our policy is to reject them initially until the user provides proof of ownership to ensure no one elseās model is being used without permission. The steps to get approval are outlined below.
Next steps: Ensure your face is clearly visible in a well-lit environment in the video. If you're submitting a 3D model avatar, please reach out to our Moderation team at [email protected], providing the rejected avatar ID and proof of ownership (e.g., a screenshot from the software you used). Additional evidence may be required on a case-by-case basis.
ā
āNo audio detected in video footageā
API Error Code: Missing voices
What this means: Your video footage is missing audio. While we understand that some users prefer not to use their own voice when creating avatars and videos, having both audio and video is crucial for our algorithm to generate accurate lip-syncing for your avatar. To get the best results, we recommend uploading a video with audio so our system can properly create your avatar with lip-sync capability. Don't worryāyou can swap the voice later in the AI Studio and never have to use your own voice!
ā
Next steps: Please re-submit your footage in a new avatar process and make sure your video has clear audio for optimal results.
āFootage too short / Footage too longā
API Error: Footage is too short or too long
What this means: Your footage is either shorter or longer than the required length.
Next steps: Please start the process again and make sure your avatar footage is between 30 seconds and 5 minutes.
āInappropriate visuals detectedā
API Error: NSFW content detected
What this means: The system detected inappropriate visuals, such as nudity, in your avatar footage. Our platform strictly prohibits both, in accordance with AI safety protocols. Repeated attempts to upload such content could result in an account ban.
Next steps: Please restart the process, ensuring your avatar footage does not include minors or nudity.
ā
āCelebrity face detectedā
What this means: Our moderation system is highly skilled at recognizing celebrities from all over the world. Due to the abundance of public footage available for well-known figures, there are more frequent attempts to create unauthorized "deepfakes" of their avatars. As a result, if our system detects a celebrity face in the footage, it automatically flags it for human moderation for authenticity verification.
Next steps: If your avatar was rejected with this error, please follow these steps:
Email us at [email protected] to request a human review of your avatar.
While not required, itās helpful if you can provide a copy of the consent footage.
āFailed to track your faceā
āWhat this means:Ā The system had difficulty tracking your face throughout the footage. This usually happens when there's too much movement, or your face isn't consistently visible.
āNext steps:Ā Re-record your footage, making sure your face is stable and clearly visible throughout the entire recording. Avoid excessive head movements and ensure good lighting.
āLarge face angleā
āWhat this means:Ā Your face wasn't facing the camera directly throughout the recording. The system requires a front-facing view to properly create your avatar.
āNext steps:Ā Re-record your footage while facing the camera directly at all times. Avoid turning your head or showing your profile.
āVideo format not supportedā
āWhat this means:Ā The video file you uploaded is in a format that our system doesn't support.
ā
āNext steps:Ā Convert your video to a supported format (MP4 is recommended) and re-upload.
āhttp download failedā
What this means:Ā The system couldn't download your video from the URL you provided. This can happen if the URL is private, expired, or inaccessible.
āNext steps:Ā Ensure your URL is publicly accessible and hasn't expired. Alternatively, try uploading the file directly instead of using a URL.
āInstant avatar not foundā
What this means:Ā The avatar couldn't be located or may be corrupted.
āNext steps:Ā Try creating a new avatar from the beginning. If the issue persists, contact support.
Other Types of Errors
āServer Errorā/ āWorkflow Internal Errorā
What this means: There was an issue on our end. You can try again right away, and if it fails a second time, it might indicate a larger problem. While these issues are typically resolved within a few hours, you can reach out to our support team via email or chat for assistance after a period of waiting, or simply check back tomorrow, and it should be fixed!
Next steps: Wait a few hours or contact support for a more specific time estimate on the resolution.
āMultiple failed attemptsā
What this means: After three unsuccessful attempts to create your avatar due to the issues mentioned above, your account may receive an avatar ban. This restriction can only be lifted by our support team.
Next steps: Please reach out to our moderation team at [email protected] to resolve the issue.
API Only Errors
This part discusses errors that are only shown to users trying to create digital twins avatars via API, the specific error codes they receive, and how to fix it.
āAPI Error: Footage resolution is too low or too highā
What this means: The video resolution is outside the supported range for avatar creation. This can happen when the footage is either too small/low-quality or too large for the system to process correctly.
ā
Next steps: Please re-record or re-export the video using a supported resolution, then upload it again.
āAPI Error: Footage resolution is too highā
What this means: The uploaded video resolution is too large for the system to process.
Next steps: Please downscale or compress the video, then try uploading it again.
āAPI Error: Empty video streamā
What this means: The uploaded file does not contain a readable video stream. This can happen if the file is audio-only, blank, exported incorrectly, or corrupted.
Next steps: Please upload a new video file and make sure it plays correctly on your device before uploading.
āAPI Error: Multiple scenes detectedā
What this means: The system detected multiple scenes, cuts, transitions, or camera changes in the uploaded footage. Avatar footage should be one continuous recording.
Next steps: Please upload a single, unedited take with no cuts, scene changes, or transitions.
āAPI Error: Audio is too short or corruptedā
What this means: The audio in the uploaded footage is either too short, missing, or cannot be read properly by the system.
Next steps: Please re-record the video with clear, continuous audio, then upload it again.
āAPI Error: Video corruptedā
What this means: The uploaded video file is damaged or cannot be read properly by the system.
Next steps: Please re-export the video or record a new version, then try uploading it again.
āAPI Error: Footage validation failedā
āAPI Error: Instant avatar group identity match failedā
What this means: The uploaded footage did not match the existing consent video and identity of this avatar group (slot). It's possible you accidentally uploaded a footage of a different person than this current avatar slot identity. This also may be related to video quality, lighting, face visibility, scene changes, or other footage issues.
Next steps: Please review your footage and upload a new recording with clear lighting, a visible face, clean audio, and no cuts or scene changes.
āAPI Error: Consent video empty video streamā
What this means: The consent video does not contain a readable video stream. This can happen if the file is blank, audio-only, exported incorrectly, or corrupted.
Next steps: Please upload a new consent video and make sure it plays correctly on your device before uploading.
āAPI Error: Instant avatar erroredā
What this means: Something went wrong while processing the instant avatar.
Next steps: Please try creating the avatar again. If it keeps failing, please contact HeyGen support, as a repeated failure here usually points to a processing issue on our side rather than your footage.
ā
