{"record":{"id":"e07bdc9742734f96","repo":"Comfy-Org/ComfyUI","slug":"heygen-accepts-at-most-3-reference-images-got-n","errorCode":null,"errorMessage":"HeyGen accepts at most 3 reference images; got {n_images}.","messagePattern":"HeyGen accepts at most 3 reference images; got (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_heygen.py","lineNumber":548,"sourceCode":"    async def execute(\n        cls,\n        source: dict,\n    ) -> IO.NodeOutput:\n        payload: dict = {\"name\": \"ComfyUI Avatar\"}\n        if source[\"source\"] == \"photo\":\n            image = downscale_image_tensor_by_max_side(source[\"identity_photo\"], max_side=2000)\n            image_url = await upload_image_to_comfyapi(cls, image, mime_type=\"image/png\", total_pixels=None)\n            payload[\"type\"] = \"photo\"\n            payload[\"file\"] = {\"type\": \"url\", \"url\": image_url}\n        else:\n            validate_string(source[\"prompt\"], strip_whitespace=True, min_length=1, max_length=1000)\n            payload[\"type\"] = \"prompt\"\n            payload[\"prompt\"] = source[\"prompt\"]\n            ref_tensors = [t for t in (source.get(\"reference_images\") or {}).values() if t is not None]\n            if ref_tensors:\n                n_images = sum(get_number_of_images(t) for t in ref_tensors)\n                if n_images > 3:\n                    raise ValueError(f\"HeyGen accepts at most 3 reference images; got {n_images}.\")\n                scaled = [downscale_image_tensor_by_max_side(t, max_side=2000) for t in ref_tensors]\n                ref_urls = await upload_images_to_comfyapi(\n                    cls, scaled, max_images=3, mime_type=\"image/png\", total_pixels=None\n                )\n                payload[\"reference_images\"] = [{\"type\": \"url\", \"url\": u} for u in ref_urls]\n        created = await sync_op_raw(\n            cls,\n            ApiEndpoint(path=_AVATARS_PATH, method=\"POST\"),\n            data=payload,\n        )\n        look_id = ((created.get(\"data\") or {}).get(\"avatar_item\") or {}).get(\"id\")\n        if not look_id:\n            raise ValueError(f\"HeyGen did not return an avatar: {created}\")\n        final = await poll_op_raw(\n            cls,\n            ApiEndpoint(path=f\"{_LOOKS_PATH}/{look_id}\"),\n            # A missing status means the look needed no training and is ready.\n            status_extractor=lambda r: (r.get(\"data\") or {}).get(\"status\") or \"completed\",","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_heygen.py#L530-L566","documentation":"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.","triggerScenarios":"Selecting source type 'prompt' and connecting reference image inputs whose summed image count (batches included) is greater than 3.","commonSituations":"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.","solutions":["Disconnect images until at most 3 remain in total","Split batched tensors and select specific frames instead of passing whole batches","Pick the 3 most identity-relevant references for best results"],"exampleFix":"// before: single reference slot wired to a 4-image batch -> error\n// after: select 3 images from the batch before connecting","handlingStrategy":"validation","validationCode":"from comfy_api_nodes.utils import get_number_of_images\n\ndef avatar_refs_ok(source: dict, limit: int = 3) -> bool:\n    refs = [t for t in (source.get('reference_images') or {}).values() if t is not None]\n    return sum(get_number_of_images(t) for t in refs) <= limit","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Cap avatar reference slots at 3 images including batch contents","Flatten batches and select the best 3 references explicitly"],"tags":["heygen","avatar-creation","reference-images","input-validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}