{"record":{"id":"22816bd984b800e3","repo":"Comfy-Org/ComfyUI","slug":"a-maximum-of-7-reference-images-is-supported-tot","errorCode":null,"errorMessage":"A maximum of 7 reference images is supported; {total_images} are connected.","messagePattern":"A maximum of 7 reference images is supported; (.+?) are connected\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_grok.py","lineNumber":992,"sourceCode":"                  $imgCost := $is15 ? 0.01 : 0.002;\n                  $price := ($rate * $dur + $imgCost * $refs) * 1.43;\n                  {\"type\":\"usd\",\"usd\": $price}\n                )\n                \"\"\",\n            ),\n        )\n\n    @classmethod\n    async def execute(\n        cls,\n        prompt: str,\n        model: dict,\n        seed: int,\n    ) -> IO.NodeOutput:\n        validate_string(prompt, strip_whitespace=True, min_length=1)\n        total_images = sum(get_number_of_images(t) for t in model[\"reference_images\"].values())\n        if total_images > 7:\n            raise ValueError(f\"A maximum of 7 reference images is supported; {total_images} are connected.\")\n        reference_audios = None\n        if model[\"model\"] == \"grok-imagine-video-1.5\":\n            voices = [model.get(f\"voice_{i}\", \"none\") for i in range(1, 4)]\n            reference_audios = [VoiceReferenceObject(voice_id=v) for v in voices if v != \"none\"] or None\n            prompt = _normalize_grok_reference_prompt(prompt, total_images=total_images, voices=voices)\n        ref_image_urls = await upload_images_to_comfyapi(\n            cls,\n            list(model[\"reference_images\"].values()),\n            mime_type=\"image/png\",\n            wait_label=\"Uploading base images\",\n            max_images=7,\n        )\n        initial_response = await sync_op(\n            cls,\n            ApiEndpoint(path=\"/proxy/xai/v1/videos/generations\", method=\"POST\"),\n            data=VideoGenerationRequest(\n                model=_GROK_VIDEO_MODEL_API_IDS.get(model[\"model\"], model[\"model\"]),\n                reference_images=[InputUrlObject(url=i) for i in ref_image_urls],","sourceCodeStart":974,"sourceCodeEnd":1010,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_grok.py#L974-L1010","documentation":"Thrown by the Grok reference-image video node when the combined number of images across all reference_images slots exceeds 7. Each connected tensor's batch count is summed (sum of get_number_of_images over model['reference_images'].values()), matching xAI's limit of 7 reference images per request. The check runs before any upload, so it fails before spending API credits.","triggerScenarios":"Connecting several reference image inputs where the total image count (including multi-image batches in a single tensor) exceeds 7, on any model, but especially grok-imagine-video-1.5 workflows that use reference images.","commonSituations":"Feeding a batched tensor of character/scene references into one reference slot, or connecting many single-image slots each containing a multi-frame GIF.","solutions":["Reduce connected reference images so the total count (including batches) is at most 7","Split batched tensors and select only the needed frames before connecting","Curate the strongest 7 or fewer references; more images rarely improve identity fidelity"],"exampleFix":"// before: one reference_images slot receives a batch of 8 images -> error\n// after: limit batch to 7 before connecting\n// (workflow) Load Image batch=8 -> ImageBatchToImageList -> select 7 -> Grok reference images","handlingStrategy":"validation","validationCode":"from comfy_api_nodes.utils import get_number_of_images\n\ndef total_refs_ok(model: dict, limit: int = 7) -> bool:\n    return sum(get_number_of_images(t) for t in model['reference_images'].values()) <= limit","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Count batches, not wires — a single slot can carry many images","Curate references down before connecting to stay under 7"],"tags":["grok","xai","video-generation","reference-images","input-validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}