Kandinsky S2V Reference Image:
KandinskyS2VReferenceImage prepares a reference frame for Kandinsky S2V by fitting it to one of the model’s trained image sizes: 512×512, 512×768, or 768×512 pixels, expressed as width × height. It automatically chooses the size whose aspect ratio is closest to the original frame, then scales the frame proportionally until it completely covers that size and crops away any excess from the center. This preserves the proportions of your subject rather than stretching it, although details near the edges may be removed. Its main purpose is to make reference preparation straightforward and keep the frame within the resolutions supported by the model before VAE encoding and video generation.
Kandinsky S2V Reference Image Input Parameters:
image
A required IMAGE containing the reference picture you want to prepare for Kandinsky S2V, typically supplied by Load Image. The node processes only the first image if you supply a batch; the remaining images are ignored. It measures that first image’s width-to-height ratio and selects the closest trained resolution automatically, so the original composition determines the final orientation and how much edge content is cropped. Only the first three color channels are retained; an alpha channel, if present, is discarded rather than used to composite the picture onto a background. Before resizing, pixel values are multiplied by 255, rounded, limited to the 0–255 range, and converted to 8-bit values. Supply a standard ComfyUI image with normalized pixel values in the usual 0–1 range. No default image, minimum or maximum image dimensions, or selectable options are declared for this parameter.
Kandinsky S2V Reference Image Output Parameters:
image
An IMAGE containing a single prepared reference frame at 512×512, 512×768, or 768×512 pixels, expressed as width × height. The image is proportionally resized using bilinear interpolation and then center-cropped to exactly match the selected resolution. It is returned as floating-point pixel values normalized to the 0–1 range, with a batch size of one. This is still an ordinary image, not an encoded latent: connect it to the standard VAE Encode node, using the HunyuanVideo VAE required by the Kandinsky S2V workflow, and pass that encoded result to the sampler’s reference_latent connection. Matching the trained dimensions helps the downstream sampler accept the reference frame without resolution-related validation errors.
Kandinsky S2V Reference Image Usage Tips:
-
Use the reference branch
Load Image → Kandinsky S2V Reference Image → VAE Encode → Kandinsky S2V Sampler. Connect VAE Encode’s latent output to the sampler’sreference_latentinput. -
Keep important subjects near the center and leave some space around faces, hair, hands, and other essential details. The node always crops from the center and has no controls for repositioning the crop.
-
Prepare your composition near a supported aspect ratio when you want to minimize cropping: 1:1 for 512×512, 2:3 for 512×768, or 3:2 for 768×512. For example, a 1920×1080 landscape image selects 768×512 and loses some content from the left and right edges.
-
Preview the prepared image before encoding it. If the framing is unsuitable, crop or reposition the original image upstream; this node has no manual resolution, crop-position, or interpolation settings.
-
Supply one reference image at a time. If you connect an image batch, only its first frame is used, so select the intended frame before this node.
-
Composite transparent artwork onto your intended background before preparation. The node discards alpha information and does not automatically place transparent areas over a chosen background.
-
Avoid resizing the prepared image after this node and before VAE Encode. Changing its dimensions can take it outside the supported resolution set and cause the sampler to reject the encoded reference.
Kandinsky S2V Reference Image Common Errors and Solutions:
Important parts of the reference image are cropped off
- Explanation: This is an expected consequence of resizing to cover the selected resolution and then center-cropping, not an explicit error message. Content near the edges can be removed when the original aspect ratio differs from the selected trained ratio.
- Solution: Reframe the image upstream so your subject is centered with extra space around important details. Use a composition close to 1:1, 2:3, or 3:2 and preview the prepared image before encoding.
Only the first image in a batch is processed
- Explanation: The node explicitly selects the first frame and returns one prepared image. It does not prepare every image in a batch.
- Solution: Select the desired image before connecting it, or process separate reference images through separate executions of the reference-preparation workflow.
Transparent areas do not display as expected
- Explanation: The node keeps only the first three color channels and discards the alpha channel. It does not use transparency to blend the reference onto a background.
- Solution: Flatten or composite the image onto your preferred background upstream, then pass that completed image into this node.
IndexError when an empty image batch is supplied
- Explanation: The preparation code immediately accesses the first image. An empty batch has no first frame, so execution can fail with an indexing error; the exact message depends on the supplied image object.
- Solution: Check the upstream image source or frame-selection node and make sure it produces at least one valid image. A standard Load Image connection is a straightforward way to test the reference branch.
Kandinsky S2V expects a reference frame of [trained sizes], got [width]x[height]. Fit the image with Kandinsky S2V Reference Image before VAE Encode.
- Explanation: This validation error comes from the downstream Kandinsky S2V sampler, not the preparation node. It means the dimensions represented by the encoded reference are outside the trained resolutions. This can happen if preparation was bypassed or the image was resized afterward.
- Solution: Connect this node’s output directly to VAE Encode and use that encoded reference in the sampler. Remove any intervening resize operation that changes the prepared dimensions.
Kandinsky S2V expects one encoded reference frame shaped [1, C, 1, H, W], got [actual shape]. Encode a single image with the HunyuanVideo VAE.
- Explanation: This downstream sampler error indicates that the reference latent does not represent the required single reference frame. The sampler checks for one batch item and one temporal frame after accommodating supported latent layouts.
- Solution: Encode the single image returned by this node with the HunyuanVideo VAE through standard VAE Encode. Connect that latent directly to the sampler’s
reference_latentinput without combining it with other frames or latent batches.
Kandinsky S2V expects [expected channels] latent channels, got [actual channels]. Encode the reference frame with the HunyuanVideo VAE.
- Explanation: This downstream sampler error means the reference was encoded with a VAE whose latent channel count does not match the Kandinsky S2V model. Preparing the image at the correct resolution does not resolve an incompatible VAE.
- Solution: Use the HunyuanVideo VAE required by the workflow, reconnect it to VAE Encode, and encode the prepared image again before sampling.
