{"record":{"id":"e122982ba17351fc","repo":"Comfy-Org/ComfyUI","slug":"minimax-h3-reference-videos-need-at-least-5-frames","errorCode":null,"errorMessage":"MiniMax H3 reference videos need at least 5 frames (~0.2s at 24 fps)","messagePattern":"MiniMax H3 reference videos need at least 5 frames \\(~0\\.2s at 24 fps\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_minimax_h3.py","lineNumber":325,"sourceCode":"            ref_blocks.append({\"kind\": \"image\", \"latent_h\": th // 16, \"latent_w\": tw // 16, \"latent\": z})\n\n        ref_video_audios = ref_video_audios or {}\n        for name, video_frames in (ref_videos or {}).items():\n            if video_frames is None:\n                continue\n            # index-paired soundtrack: ref_video_audio_N belongs to ref_video_N\n            soundtrack = ref_video_audios.get(\"ref_video_audio_\" + name.rsplit(\"_\", 1)[-1])\n            vh, vw = video_frames.shape[1], video_frames.shape[2]\n            cw, ch = adapt_canvas(vw, vh)\n            if vw * vh < cw * ch:\n                cw = max(CANVAS_MULTIPLE, round(vw / CANVAS_MULTIPLE) * CANVAS_MULTIPLE)\n                ch = max(CANVAS_MULTIPLE, round(vh / CANVAS_MULTIPLE) * CANVAS_MULTIPLE)\n            frames = _resize(video_frames, cw, ch, \"disabled\")\n            if frames.shape[0] > frame_count:\n                frames = frames[:frame_count]\n            n = frames.shape[0]\n            if n < 5:\n                raise ValueError(\"MiniMax H3 reference videos need at least 5 frames (~0.2s at 24 fps)\")\n            while n % 17 != 5:\n                n -= 1\n            frames = frames[:n]\n            z = vae.encode(frames)\n            audio_latent, ref_audio_t = (None, 0)\n            if soundtrack is not None:\n                audio_latent, ref_audio_t = _encode_ref_audio(audio_vae, soundtrack)\n                # the soundtrack gets its own <Audio j> label, emitted before <Video k>\n                ref_items.append({\"type\": \"audio\"})\n            # Qwen sees the video at 2 fps with timestamps\n            sample_idx = list(range(0, frames.shape[0], FPS // 2))\n            qwen_frames = frames[sample_idx]\n            ref_items.append({\"type\": \"video\", \"data\": qwen_frames,\n                              \"timestamps\": [i / 2.0 for i in range(len(sample_idx))]})\n            ref_blocks.append({\"kind\": \"video_audio\" if ref_audio_t else \"video\",\n                               \"latent_t\": z.shape[2], \"latent_h\": ch // 16, \"latent_w\": cw // 16,\n                               \"ref_audio_t\": ref_audio_t, \"latent\": z, \"audio_latent\": audio_latent})\n","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_minimax_h3.py#L307-L343","documentation":"MiniMaxH3ReferenceToVideo requires each reference video to keep at least 5 frames after resizing/canvas adaptation and trimming to frame_count, because H3 video tokenization needs clips whose length is 5 mod 17 (5 being the minimum). Fewer than 5 frames cannot form a single valid video token group (~0.2s at 24 fps).","triggerScenarios":"Passing a ref video of 1-4 frames, or one trimmed by 'if frames.shape[0] > frame_count: frames = frames[:frame_count]' down to under 5 frames because frame_count is small.","commonSituations":"Using a single image or a 2-3 frame GIF as a 'reference video'; frame_count limits derived from a very short target latent truncating the reference; ffmpeg export producing tiny clips.","solutions":["Supply a reference video with at least 5 frames (ideally 5, 22, 39... frames for exact token fit).","For a single reference image, use the reference-image input path instead of the video input.","Raise frame_count so the trim step cannot cut the ref below 5 frames."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"n = min(video_frames.shape[0], frame_count)\nif n < 5:\n    raise UserFacingError('reference video needs >= 5 frames')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use reference clips of at least 5 frames (ideally 5 mod 17).","Use the image reference input for stills instead of video.","Check frame_count before trimming long refs."],"tags":["minimax-h3","reference-video","min-frames","validation"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}