feat(recall): support model-free reference images in recall API#9045
Draft
feat(recall): support model-free reference images in recall API#9045
Conversation
The recall parameters API previously exposed only `loras`, `control_layers`, and `ip_adapters`. This meant reference images used by architectures that feed images directly into the main model — FLUX.2 Klein, FLUX Kontext, and Qwen Image Edit — could not be sent through the recall endpoint at all: they have no adapter model to resolve, so they could not ride in the `ip_adapters` list. This change adds a new `reference_images` field on RecallParameter that carries only an `image_name`. The backend validates the file exists in outputs/images and forwards the resolved metadata (width/height) in the broadcast event. The frontend's recall handler picks the right config type (`flux2_reference_image` / `flux_kontext_reference_image` / `ip_adapter` fallback) via getDefaultRefImageConfig() based on the currently-selected main model, matching the behavior of a manual drag-and-drop, and dispatches `refImagesRecalled` with replace:false so these append rather than clobber any adapters already applied in the same event. Also consolidates the two existing docs under docs/contributing/RECALL_PARAMETERS/ (RECALL_PARAMETERS_API.md and RECALL_API_LORAS_CONTROLNETS_IMAGES.md) into a single RECALL_PARAMETERS_API.md that documents the full request schema including the new field. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The original recall_parameters router (PR #8758) shipped without any unit tests for its three collection fields. This commit backfills that coverage alongside the reference_images tests added in the previous commit. The resolver helpers (resolve_model_name_to_key, load_image_file, process_controlnet_image) are monkey-patched via module-level attribute replacement so each test can pin down a specific resolution outcome without spinning up the model manager or an image-files service. Two small factory helpers (make_name_to_key_stub / make_load_image_file_stub) make that ergonomic. New coverage: * LoRAs — multi-entry resolution + weight/is_enabled pass-through, silent drop on unresolvable names, is_enabled default of True. * Control layers — ControlNet resolution precedence, fall-through to T2I Adapter and Control LoRA in order, missing image gracefully warned-and-continued, processed_image attached when the processor returns data, unresolvable entries dropped. * IP Adapters — IPAdapter-before-FluxRedux lookup order, method / image_influence pass-through, missing image gracefully warned-and- continued, unresolvable entries dropped. * Combined happy path — full request with prompts + model + all four collection fields, verifying every resolved value reaches the broadcast payload. * Main-model drop — an unresolvable main model is scrubbed from the broadcast so the frontend never receives a stale model name. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
github-actions
bot
added
api
python
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
*** This PR is dependent on #9018 . Wait until the latter PR is merged. ***
Summary
The current
recall_parametersAPI can recall reference images that are attached to the denoiser via ip_adapters, but fails when the reference image is attached directly to the model, as happens with Flux.2 and Qwen Image Edit. This PR corrects the problem and allows both types of reference image to be recalled.In addition, there was no test coverage of the recall_parameters API at all. This PR adds tests for recall of basic generation parameters, ip_adapters, direct_reference images, LoRAs, and controlNets.
Related Issues / Discussions
QA Instructions
It is easiest to test using the Swagger doc execution feature.
outputs/imagesdirectory./api/v1/recall/{queue_id}When submitted, the positive prompt and the model should change as specified (these are the positive controls), and the selected reference image should appear.
Merge Plan
Simple merge.
Checklist
What's Newcopy (if doing a release after this PR)