Discussions

Dear HeyGen Support Team,

I'm experiencing a critical bug with the Avatar IV API (v2/video/av4/generate) that is causing generation failures and wasting my API credits.

The Issue

Error Message:

{
  "code": "INVALID_PARAMETER",
  "detail": "Unsupported download url: s3://surreal-product/image/67fdeda596704d3e901349bc086db5a1/original",
  "message": "Unsupported download url: s3://surreal-product/image/67fdeda596704d3e901349bc086db5a1/original"
}

Workflow

1. Upload image via POST /v1/asset

   • Response:

     {
     "image_key": "image/67fdeda596704d3e901349bc086db5a1/original",
     "heygen_url": "https://resource2.heygen.ai/image/67fdeda596704d3e901349bc086db5a1/original"
     }

   • Upload succeeds ✅

2. Generate video via POST /v2/video/av4/generate

   • Request payload:

     {
     "image_key": "image/67fdeda596704d3e901349bc086db5a1/original",
     "script": "...",
     "voice_id": "...",
     "video_orientation": "portrait",
     "fit": "cover",
     "custom_motion_prompt": "...",
     "enhance_custom_motion_prompt": true
     }

   • Request accepted, returns video_id ✅

3. Poll status via GET /v1/video_status.get

   • Status: failed ❌
   • Error: "Unsupported download url: s3://..."

Root Cause Analysis

It appears that:

• The /v1/asset upload endpoint returns an image_key in the format: "image/{id}/original"
• When Avatar IV tries to use this image_key, it converts it to an internal S3 path: s3://surreal-product/image/{id}/original
• The Avatar IV service cannot resolve this internal S3 URL, causing the generation to fail

Financial Impact

This bug has caused multiple failed generations, wasting API credits:

• Each Avatar IV generation attempt costs credits
• Failed generations are NOT refunded
• i create 8 Clips to concat it to 1 Video if 1 Clip fail, i have to restart the whole process

Questions

1. Is image_key the correct parameter for Avatar IV?

   • Should I use image_url (the HTTPS URL from upload response) instead?
   • Your documentation doesn't clearly specify which parameter Avatar IV expects

2. Why does Avatar IV fail to resolve the internal S3 URL?

   • This seems like an internal HeyGen infrastructure issue
   • The upload endpoint and Avatar IV service appear to be incompatible

3. Can you refund the wasted credits?

   • These failures were caused by unclear API documentation and/or an internal bug
   • I would appreciate a credit refund for the failed generations

Temporary Workaround

I'm now testing with image_url instead of image_key:

{
"image_url": "https://resource2.heygen.ai/image/67fdeda596704d3e901349bc086db5a1/original",
// ... rest of payload
}

Please confirm if this is the correct approach.

Request

1. ✅ Clarify the Avatar IV documentation (which image parameter to use)
2. ✅ Fix the internal S3 URL resolution issue (if image_key should work)
3. ✅ Refund credits for failed generations caused by this bug

Thank you for your assistance. Looking forward to your response.

Best regards,
sebastian