Use reference images

What references are for

Reference images guide the model's visual understanding of a character or object. They are not automatically timed keyframes, separate animation layers, or a promise to merge every detail exactly. Use a coherent set showing the same subject and describe the intended motion.

Choose reference-image mode in Studio. Add the first image, choose a compatible model, then fill the extra reference slots the interface offers. Use high-quality, consistent inputs rather than unrelated images.

The image limit includes the first image

max_reference_images is the total count, not the number of extra slots. If discovery returns a limit of 3, the first image plus two additional references fills that limit. This is an illustration, not a universal product limit.

The interface derives available slots from the selected model. When changing models, verify which references remain active; do not assume all previously selected images will be used. If reference_image_duration_seconds is present, that model fixes the reference workflow's duration. Other models may offer different choices.

Do not assume reference mode is limited to one named provider or always uses eight seconds. Read models and prompts.

Keep the set consistent

Use matching character proportions, costume, and background treatment. Conflicting viewpoints or clothing can compete with the desired motion. Start with the minimum useful set, inspect the result, then make a deliberate new request if it needs revision.

First + last frame is the appropriate mode for an explicit end pose. Reference images cannot be combined with last_frame in the public request. Input canvas is not supported in reference-image mode.

For Alpha Key generation, every participating reference, including the first image, must contain meaningful Alpha. An ordinary JPEG reference cannot acquire transparency because another image has it.

API and MCP mapping

input.first_frame supplies the first reference. input.reference_images supplies the additional images; do not repeat the first image in that array. Upload each local image through the documented flow and use its completed file_id. Public image inputs do not expose Studio's internal role or label fields.

Select a live model with supports_reference_images and a compatible modes entry. Use its total image limit, duration, resolution, and mode-specific ratios when constructing the request. The generated schemas give field limits; live discovery can impose a stricter model limit.

Quote the complete image set and settings. If you add or remove a reference after approval, quote again and reconfirm the changed request. Follow the MCP workflow for local-byte transfer and safe generation.