feat: support multiple reference images with model-aware API mapping

Replace singular reference_image field with reference_images list to
support an arbitrary number of reference images. Map them to the correct
BFL API parameter names based on model family:
- flux-2-*: input_image, input_image_2, ..., input_image_8
- flux-kontext-*: input_image, input_image_2, ..., input_image_4
- flux 1.x: image_prompt (single)

BREAKING CHANGE: reference_image config field renamed to reference_images (list).

bulkgen/builder.py

@@ -51,8 +51,7 @@ def _collect_dep_files(
     """Collect all dependency file paths for a target."""
     target_cfg = config.targets[target_name]
     deps: list[str] = list(target_cfg.inputs)
-    if target_cfg.reference_image is not None:
-        deps.append(target_cfg.reference_image)
+    deps.extend(target_cfg.reference_images)
     deps.extend(target_cfg.control_images)
     return [project_dir / d for d in deps]
 
@@ -65,19 +64,18 @@ def _collect_extra_params(target_name: str, config: ProjectConfig) -> dict[str,
         params["width"] = target_cfg.width
     if target_cfg.height is not None:
         params["height"] = target_cfg.height
-    if target_cfg.reference_image is not None:
-        params["reference_image"] = target_cfg.reference_image
+    if target_cfg.reference_images:
+        params["reference_images"] = tuple(target_cfg.reference_images)
     if target_cfg.control_images:
         params["control_images"] = tuple(target_cfg.control_images)
     return params
 
 
 def _collect_all_deps(target_name: str, config: ProjectConfig) -> list[str]:
-    """Collect all dependency names (inputs + reference_image + control_images)."""
+    """Collect all dependency names (inputs + reference_images + control_images)."""
     target_cfg = config.targets[target_name]
     deps: list[str] = list(target_cfg.inputs)
-    if target_cfg.reference_image is not None:
-        deps.append(target_cfg.reference_image)
+    deps.extend(target_cfg.reference_images)
     deps.extend(target_cfg.control_images)
     return deps
 

bulkgen/config.py

@@ -34,7 +34,7 @@ class TargetConfig(BaseModel):
     prompt: str
     model: str | None = None
     inputs: list[str] = []
-    reference_image: str | None = None
+    reference_images: list[str] = []
     control_images: list[str] = []
     width: int | None = None
     height: int | None = None

bulkgen/graph.py

@@ -26,8 +26,7 @@ def build_graph(config: ProjectConfig, project_dir: Path) -> nx.DiGraph[str]:
         graph.add_node(target_name)
 
         deps: list[str] = list(target_cfg.inputs)
-        if target_cfg.reference_image is not None:
-            deps.append(target_cfg.reference_image)
+        deps.extend(target_cfg.reference_images)
         deps.extend(target_cfg.control_images)
 
         for dep in deps:

bulkgen/providers/image.py

@@ -18,6 +18,32 @@ def _encode_image_b64(path: Path) -> str:
     return base64.b64encode(path.read_bytes()).decode("ascii")
 
 
+# Parameter names for reference images, keyed by model prefix.
+_INPUT_IMAGE_KEYS = ["input_image"] + [f"input_image_{i}" for i in range(2, 9)]
+_IMAGE_PROMPT_KEYS = ["image_prompt"]
+
+
+def _ref_image_keys(model: str) -> list[str]:
+    """Return the ordered API parameter names for reference images."""
+    if model.startswith("flux-2-"):
+        return _INPUT_IMAGE_KEYS  # up to 8
+    if model.startswith("flux-kontext-"):
+        return _INPUT_IMAGE_KEYS[:4]  # up to 4
+    return _IMAGE_PROMPT_KEYS  # flux 1.x: single image_prompt
+
+
+def _add_reference_images(
+    inputs: dict[str, object],
+    reference_images: list[str],
+    model: str,
+    project_dir: Path,
+) -> None:
+    """Encode reference images and add them under the correct API keys."""
+    keys = _ref_image_keys(model)
+    for key, ref_name in zip(keys, reference_images, strict=False):
+        inputs[key] = _encode_image_b64(project_dir / ref_name)
+
+
 class ImageProvider(Provider):
     """Generates images via the BlackForestLabs API."""
 
@@ -44,9 +70,10 @@ class ImageProvider(Provider):
         if target_config.height is not None:
             inputs["height"] = target_config.height
 
-        if target_config.reference_image is not None:
-            ref_path = project_dir / target_config.reference_image
-            inputs["image_prompt"] = _encode_image_b64(ref_path)
+        if target_config.reference_images:
+            _add_reference_images(
+                inputs, target_config.reference_images, resolved_model, project_dir
+            )
 
         for control_name in target_config.control_images:
             ctrl_path = project_dir / control_name

tests/test_builder.py

@@ -91,7 +91,7 @@ class TestCollectHelpers:
                     "out.png": {
                         "prompt": "x",
                         "inputs": ["input.txt"],
-                        "reference_image": "ref.png",
+                        "reference_images": ["ref.png"],
                         "control_images": [],
                     }
                 }
@@ -110,7 +110,7 @@ class TestCollectHelpers:
                         "prompt": "x",
                         "width": 512,
                         "height": 256,
-                        "reference_image": "ref.png",
+                        "reference_images": ["ref.png"],
                     }
                 }
             }
@@ -118,7 +118,7 @@ class TestCollectHelpers:
         params = _collect_extra_params("out.png", config)
         assert params["width"] == 512
         assert params["height"] == 256
-        assert params["reference_image"] == "ref.png"
+        assert params["reference_images"] == ("ref.png",)
 
     def test_collect_extra_params_empty(self, write_config: WriteConfig) -> None:
         config = write_config({"targets": {"out.txt": {"prompt": "x"}}})
@@ -131,7 +131,7 @@ class TestCollectHelpers:
                     "out.png": {
                         "prompt": "x",
                         "inputs": ["a.txt"],
-                        "reference_image": "ref.png",
+                        "reference_images": ["ref.png"],
                         "control_images": ["c1.png", "c2.png"],
                     }
                 }

tests/test_config.py

@@ -45,7 +45,7 @@ class TestLoadConfig:
                     "width": 1920,
                     "height": 480,
                     "inputs": ["ref.png"],
-                    "reference_image": "ref.png",
+                    "reference_images": ["ref.png"],
                     "control_images": ["ctrl.png"],
                 },
                 "story.md": {
@@ -66,7 +66,7 @@ class TestLoadConfig:
         assert banner.model == "flux-dev"
         assert banner.width == 1920
         assert banner.height == 480
-        assert banner.reference_image == "ref.png"
+        assert banner.reference_images == ["ref.png"]
         assert banner.control_images == ["ctrl.png"]
 
         story = config.targets["story.md"]

tests/test_graph.py

@@ -66,7 +66,7 @@ class TestBuildGraph:
     ) -> None:
         _ = (project_dir / "ref.png").write_bytes(b"\x89PNG")
         config = write_config(
-            {"targets": {"out.png": {"prompt": "x", "reference_image": "ref.png"}}}
+            {"targets": {"out.png": {"prompt": "x", "reference_images": ["ref.png"]}}}
         )
         graph = build_graph(config, project_dir)
         assert graph.has_edge("ref.png", "out.png")

tests/test_providers.py

@@ -120,13 +120,13 @@ class TestImageProvider:
             assert inputs["width"] == 1920
             assert inputs["height"] == 480
 
-    async def test_image_with_reference_image(
+    async def test_image_with_reference_image_flux1(
         self, project_dir: Path, image_bytes: bytes
     ) -> None:
         ref_path = project_dir / "ref.png"
         _ = ref_path.write_bytes(b"reference image data")
 
-        target_config = TargetConfig(prompt="Like this", reference_image="ref.png")
+        target_config = TargetConfig(prompt="Like this", reference_images=["ref.png"])
         bfl_result, mock_http = _make_bfl_mocks(image_bytes)
 
         with (
@@ -142,7 +142,7 @@ class TestImageProvider:
                 target_name="out.png",
                 target_config=target_config,
                 resolved_prompt="Like this",
-                resolved_model="flux-kontext-pro",
+                resolved_model="flux-pro-1.1",
                 project_dir=project_dir,
             )
 
@@ -151,6 +151,71 @@ class TestImageProvider:
             assert "image_prompt" in inputs
             assert inputs["image_prompt"] == encode_image_b64(ref_path)
 
+    async def test_image_with_reference_images_flux2(
+        self, project_dir: Path, image_bytes: bytes
+    ) -> None:
+        ref1 = project_dir / "ref1.png"
+        ref2 = project_dir / "ref2.png"
+        _ = ref1.write_bytes(b"ref1 data")
+        _ = ref2.write_bytes(b"ref2 data")
+
+        target_config = TargetConfig(
+            prompt="Combine", reference_images=["ref1.png", "ref2.png"]
+        )
+        bfl_result, mock_http = _make_bfl_mocks(image_bytes)
+
+        with (
+            patch("bulkgen.providers.image.BFLClient") as mock_cls,
+            patch("bulkgen.providers.image.httpx.AsyncClient") as mock_http_cls,
+        ):
+            mock_generate = AsyncMock(return_value=bfl_result)
+            mock_cls.return_value.generate = mock_generate
+            mock_http_cls.return_value = mock_http
+
+            provider = ImageProvider(api_key="test-key")
+            await provider.generate(
+                target_name="out.png",
+                target_config=target_config,
+                resolved_prompt="Combine",
+                resolved_model="flux-2-pro",
+                project_dir=project_dir,
+            )
+
+            call_args = mock_generate.call_args
+            inputs = call_args[0][1]
+            assert inputs["input_image"] == encode_image_b64(ref1)
+            assert inputs["input_image_2"] == encode_image_b64(ref2)
+
+    async def test_image_with_reference_image_kontext(
+        self, project_dir: Path, image_bytes: bytes
+    ) -> None:
+        ref_path = project_dir / "ref.png"
+        _ = ref_path.write_bytes(b"reference image data")
+
+        target_config = TargetConfig(prompt="Edit", reference_images=["ref.png"])
+        bfl_result, mock_http = _make_bfl_mocks(image_bytes)
+
+        with (
+            patch("bulkgen.providers.image.BFLClient") as mock_cls,
+            patch("bulkgen.providers.image.httpx.AsyncClient") as mock_http_cls,
+        ):
+            mock_generate = AsyncMock(return_value=bfl_result)
+            mock_cls.return_value.generate = mock_generate
+            mock_http_cls.return_value = mock_http
+
+            provider = ImageProvider(api_key="test-key")
+            await provider.generate(
+                target_name="out.png",
+                target_config=target_config,
+                resolved_prompt="Edit",
+                resolved_model="flux-kontext-pro",
+                project_dir=project_dir,
+            )
+
+            call_args = mock_generate.call_args
+            inputs = call_args[0][1]
+            assert inputs["input_image"] == encode_image_b64(ref_path)
+
     async def test_image_no_sample_url_raises(self, project_dir: Path) -> None:
         target_config = TargetConfig(prompt="x")