Comfy-Org/ComfyUI · error · ValueError

HeyGen did not return an avatar: {created}

Error message

HeyGen did not return an avatar: {created}

What it means

Thrown after POSTing to HeyGen's avatar-creation endpoint when the response contains no data.avatar_item.id. As with other HeyGen creation calls, the node needs the returned id to poll the look-training job on _LOOKS_PATH; without it the only recourse is to inspect the raw response embedded in the message.

Source

Thrown at comfy_api_nodes/nodes_heygen.py:561

            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",
            failed_statuses=["failed", "pending_consent"],
            poll_interval=5.0,
        )
        data = final["data"]
        if data.get("preview_image_url"):
            preview = await download_url_to_image_tensor(data["preview_image_url"])
        else:
            preview = torch.zeros(1, 64, 64, 3)
        PromptServer.instance.send_progress_text(
            f"Please save the avatar_id for reuse.\n\navatar_id: {look_id}",
            cls.hidden.unique_id,
        )
        return IO.NodeOutput(look_id, preview)

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Inspect the response body in the error message for HeyGen's actual error code
2. Soften/reword the avatar prompt if moderation is indicated
3. Verify account credits and avatar-creation access
4. Retry once — transient 5xx-shaped payloads occasionally surface here

try:
    await create_avatar(...)
except ValueError as e:
    if 'did not return an avatar' in str(e):
        # response body inside the message carries HeyGen's reason (moderation/credits)
        log_and_surface(str(e))
        raise

When it happens

Trigger: HeyGen returns an error payload instead of a creation result: invalid prompt (length is pre-validated to 1-1000, so more likely content policy), photo moderation rejection, quota/auth failure, or schema drift in the /v2/avatars response.

Common situations: Prompt text trips HeyGen content moderation; account lacks avatar-creation permission/credits; upstream API change renames avatar_item.

Related errors

• HeyGen did not return a video_id: {created}
• HeyGen accepts at most 3 reference images; got {n_images}.
• HeyGen did not return a translation ID: {created}
• HeyGen did not return an audio_url: {response}
• DurationHead requires at least one of video_tokens / audio_t

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