Skip to main content

Digital Twin Creation Error Codes

This article explains all the error codes you might encounter during avatar creation and provides solutions to help you fix them.

Written by Avi

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:

  1. The same person appears in both the consent video and the avatar footage.

  2. 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:Ā 

  1. Try reading the entire paragraph and code a bit faster—though it may sound counterintuitive, it often helps!

  2. 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:

  1. You follow the consent script and read it clearly

  2. Your face is stable and visible throughout the recording

  3. The video is under 35 seconds

  4. The audio is synchronized with the video

  5. 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:

  1. The same person appears in both the consent video and avatar footage

  2. 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:

  1. Email us at [email protected] to request a human review of your avatar.

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


​

Did this answer your question?