Comfy-Org/ComfyUI · error · ValueError

HeyGen accepts at most 3 reference images; got {n_images}.

Error message

HeyGen accepts at most 3 reference images; got {n_images}.

What it means

Thrown by HeyGen create-avatar (prompt mode) when the total number of reference images across all reference_images slots exceeds 3. Each tensor's batch count is summed just like the main image limits; the check precedes downscaling and upload, so it fails before any network cost. HeyGen's avatar-creation API accepts at most 3 reference images.

Source

Thrown at comfy_api_nodes/nodes_heygen.py:548

    async def execute(
        cls,
        source: dict,
    ) -> IO.NodeOutput:
        payload: dict = {"name": "ComfyUI Avatar"}
        if source["source"] == "photo":
            image = downscale_image_tensor_by_max_side(source["identity_photo"], max_side=2000)
            image_url = await upload_image_to_comfyapi(cls, image, mime_type="image/png", total_pixels=None)
            payload["type"] = "photo"
            payload["file"] = {"type": "url", "url": image_url}
        else:
            validate_string(source["prompt"], strip_whitespace=True, min_length=1, max_length=1000)
            payload["type"] = "prompt"
            payload["prompt"] = source["prompt"]
            ref_tensors = [t for t in (source.get("reference_images") or {}).values() if t is not None]
            if ref_tensors:
                n_images = sum(get_number_of_images(t) for t in ref_tensors)
                if n_images > 3:
                    raise ValueError(f"HeyGen accepts at most 3 reference images; got {n_images}.")
                scaled = [downscale_image_tensor_by_max_side(t, max_side=2000) for t in ref_tensors]
                ref_urls = await upload_images_to_comfyapi(
                    cls, scaled, max_images=3, mime_type="image/png", total_pixels=None
                )
                payload["reference_images"] = [{"type": "url", "url": u} for u in ref_urls]
        created = await sync_op_raw(
            cls,
            ApiEndpoint(path=_AVATARS_PATH, method="POST"),
            data=payload,
        )
        look_id = ((created.get("data") or {}).get("avatar_item") or {}).get("id")
        if not look_id:
            raise ValueError(f"HeyGen did not return an avatar: {created}")
        final = await poll_op_raw(
            cls,
            ApiEndpoint(path=f"{_LOOKS_PATH}/{look_id}"),
            # A missing status means the look needed no training and is ready.
            status_extractor=lambda r: (r.get("data") or {}).get("status") or "completed",

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Disconnect images until at most 3 remain in total
2. Split batched tensors and select specific frames instead of passing whole batches
3. Pick the 3 most identity-relevant references for best results

Example fix

// before: single reference slot wired to a 4-image batch -> error
// after: select 3 images from the batch before connecting

from comfy_api_nodes.utils import get_number_of_images

def avatar_refs_ok(source: dict, limit: int = 3) -> bool:
    refs = [t for t in (source.get('reference_images') or {}).values() if t is not None]
    return sum(get_number_of_images(t) for t in refs) <= limit

When it happens

Trigger: Selecting source type 'prompt' and connecting reference image inputs whose summed image count (batches included) is greater than 3.

Common situations: One slot receives a multi-frame GIF or a batched tensor from an upstream generator, pushing the total over 3 even with few visible wires.

Related errors

• The current maximum number of supported images is 9.
• The current maximum number of supported images is 8.
• A maximum of 7 reference images is supported; {total_images}
• A voice is required when driving the video with a text scrip
• Avatar '{avatar_label}' does not support the {engine} engine

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/e07bdc9742734f96. Report an issue: GitHub.