Add multi-reference image support + fix missing python-dotenv

- Add python-dotenv to requirements.txt (was missing, causing import error)
- Add multi-reference image support for img2img (character + pose reference)
- Add pose/style drop zone to UI with side-by-side layout
- Add multi-ref models: SeeDream Sequential, Kling O1, Qwen Multi-Angle
- Update wavespeed_provider to handle multiple image uploads

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

requirements.txt

@@ -12,4 +12,5 @@ apscheduler>=3.10.0
 httpx>=0.26.0
 pyyaml>=6.0
 python-multipart>=0.0.6
+python-dotenv>=1.0.0
 higgsfield-client>=0.1.0

src/content_engine/api/routes_generation.py

@@ -289,6 +289,7 @@ async def cancel_job(job_id: str):
 @router.post("/generate/img2img", response_model=GenerationResponse)
 async def generate_img2img(
     image: UploadFile = File(...),
+    image2: UploadFile | None = File(default=None),
     positive_prompt: str = Form(""),
     negative_prompt: str = Form(""),
     character_id: str | None = Form(None),
@@ -309,12 +310,19 @@ async def generate_img2img(
     Supports both local (ComfyUI) and cloud (WaveSpeed edit) backends.
     - Local: denoise-based img2img via ComfyUI
     - Cloud: prompt-guided editing via SeeDream/NanoBanana Edit APIs
+
+    Multi-reference: Pass a second image (pose/style reference) for models that support it.
     """
     import json as json_module
 
     job_id = str(uuid.uuid4())
     image_bytes = await image.read()
 
+    # Read second reference image if provided (for multi-ref models)
+    image_bytes_2 = None
+    if image2 is not None:
+        image_bytes_2 = await image2.read()
+
     # Parse template variables
     try:
         variables = json_module.loads(variables_json) if variables_json else {}
@@ -330,6 +338,7 @@ async def generate_img2img(
             _run_cloud_img2img(
                 job_id=job_id,
                 image_bytes=image_bytes,
+                image_bytes_2=image_bytes_2,
                 positive_prompt=positive_prompt,
                 model=checkpoint,
                 content_rating=content_rating,
@@ -491,6 +500,7 @@ async def _run_cloud_img2img(
     *,
     job_id: str,
     image_bytes: bytes,
+    image_bytes_2: bytes | None,
     positive_prompt: str,
     model: str | None,
     content_rating: str,
@@ -545,6 +555,7 @@ async def _run_cloud_img2img(
         result = await _wavespeed_provider.edit_image(
             prompt=final_prompt,
             image_bytes=image_bytes,
+            image_bytes_2=image_bytes_2,
             model=model,
             size=size,
         )

src/content_engine/api/ui.html

@@ -909,6 +909,12 @@ select { cursor: pointer; }
                 <option value="higgsfield-soul">Higgsfield Soul (Faces)</option>
                 <option value="gpt-image-1.5-edit">GPT Image 1.5 Edit</option>
               </optgroup>
+              <optgroup label="Multi-Reference (2+ images)">
+                <option value="seedream-4.5-multi">SeeDream v4.5 Sequential (up to 3)</option>
+                <option value="seedream-4-multi">SeeDream v4 Sequential (up to 3)</option>
+                <option value="kling-o1-multi">Kling O1 (up to 10 refs)</option>
+                <option value="qwen-multi-angle">Qwen Multi-Angle</option>
+              </optgroup>
               <optgroup label="NSFW Friendly">
                 <option value="seedream-4-edit">SeeDream v4 Edit</option>
                 <option value="wan-2.6-edit">WAN 2.6 Edit</option>
@@ -927,7 +933,7 @@ select { cursor: pointer; }
               </optgroup>
             </select>
             <div style="font-size:11px;color:var(--text-secondary);margin-top:4px">
-              Upload a reference image and describe changes. The model preserves faces and poses.
+              Single-ref models use character image. Multi-ref models combine both images for consistency.
             </div>
           </div>
 
@@ -1005,14 +1011,30 @@ select { cursor: pointer; }
 
           <!-- Reference image upload for img2img -->
           <div id="img2img-section" style="display:none">
-            <div class="section-title">Reference Image</div>
-            <div class="drop-zone" id="ref-drop-zone" onclick="document.getElementById('ref-file-input').click()">
-              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:32px;height:32px;opacity:0.5;margin-bottom:8px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
-              <div>Drop image here or click to browse</div>
-              <div style="font-size:11px;margin-top:4px">PNG, JPG supported</div>
+            <div style="display:grid;grid-template-columns:1fr 1fr;gap:12px">
+              <div>
+                <div class="section-title">Character Reference</div>
+                <div class="drop-zone" id="ref-drop-zone" onclick="document.getElementById('ref-file-input').click()" style="min-height:140px">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:28px;height:28px;opacity:0.5;margin-bottom:6px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+                  <div style="font-size:12px">Drop or click</div>
+                  <div style="font-size:10px;margin-top:2px;color:var(--text-secondary)">Main subject</div>
+                </div>
+                <input type="file" id="ref-file-input" accept="image/*" style="display:none" onchange="handleRefImage(this)">
+              </div>
+              <div>
+                <div class="section-title">Pose/Style Reference <span style="font-weight:400;font-size:10px;color:var(--text-secondary)">(optional)</span></div>
+                <div class="drop-zone" id="pose-drop-zone" onclick="document.getElementById('pose-file-input').click()" style="min-height:140px">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:28px;height:28px;opacity:0.5;margin-bottom:6px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+                  <div style="font-size:12px">Drop or click</div>
+                  <div style="font-size:10px;margin-top:2px;color:var(--text-secondary)">Pose or style</div>
+                </div>
+                <input type="file" id="pose-file-input" accept="image/*" style="display:none" onchange="handlePoseImage(this)">
+              </div>
             </div>
-            <input type="file" id="ref-file-input" accept="image/*" style="display:none" onchange="handleRefImage(this)">
-            <label>Denoise Strength (0 = keep original, 1 = ignore reference)</label>
+            <div style="font-size:11px;color:var(--text-secondary);margin-top:8px">
+              Multi-ref models (SeeDream Sequential, Kling O1) use both images for character consistency.
+            </div>
+            <label style="margin-top:12px">Denoise Strength (0 = keep original, 1 = ignore reference)</label>
             <div class="slider-row">
               <input type="range" id="gen-denoise" min="0" max="1" step="0.05" value="0.65" oninput="this.nextElementSibling.textContent=this.value">
               <span class="value">0.65</span>
@@ -1511,6 +1533,7 @@ let currentBatchId = null;
 let batchPollInterval = null;
 let trainingPollInterval = null;
 let refImageFile = null;
+let poseImageFile = null;
 let videoImageFile = null;
 let trainImageFiles = [];
 let trainCaptions = {};  // filename -> caption text
@@ -1663,7 +1686,7 @@ document.addEventListener('DOMContentLoaded', async () => {
 
 // --- Drop zone setup ---
 function setupDropZones() {
-  ['ref-drop-zone', 'train-drop-zone', 'video-drop-zone'].forEach(id => {
+  ['ref-drop-zone', 'pose-drop-zone', 'train-drop-zone', 'video-drop-zone'].forEach(id => {
     const zone = document.getElementById(id);
     if (!zone) return;
     zone.addEventListener('dragover', e => { e.preventDefault(); zone.classList.add('dragover'); });
@@ -1676,6 +1699,9 @@ function setupDropZones() {
         if (id === 'ref-drop-zone') {
           refImageFile = file;
           showRefPreview(file);
+        } else if (id === 'pose-drop-zone') {
+          poseImageFile = file;
+          showPosePreview(file);
         } else if (id === 'video-drop-zone') {
           videoImageFile = file;
           showVideoPreview(file);
@@ -1700,9 +1726,9 @@ function showRefPreview(file) {
   const reader = new FileReader();
   reader.onload = e => {
     zone.innerHTML = `
-      <img src="${e.target.result}">
-      <div style="margin-top:6px;font-size:12px">${file.name}</div>
-      <button class="btn btn-secondary btn-small" onclick="event.stopPropagation();clearRefImage()" style="margin-top:8px">Remove</button>
+      <img src="${e.target.result}" style="max-height:100px;max-width:100%;border-radius:4px">
+      <div style="margin-top:4px;font-size:11px">${file.name.substring(0,15)}${file.name.length > 15 ? '...' : ''}</div>
+      <button class="btn btn-secondary btn-small" onclick="event.stopPropagation();clearRefImage()" style="margin-top:4px;padding:2px 8px;font-size:10px">Remove</button>
     `;
   };
   reader.readAsDataURL(file);
@@ -1713,13 +1739,46 @@ function clearRefImage() {
   const zone = document.getElementById('ref-drop-zone');
   zone.classList.remove('has-file');
   zone.innerHTML = `
-    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:32px;height:32px;opacity:0.5;margin-bottom:8px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
-    <div>Drop image here or click to browse</div>
-    <div style="font-size:11px;margin-top:4px">PNG, JPG supported</div>
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:28px;height:28px;opacity:0.5;margin-bottom:6px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+    <div style="font-size:12px">Drop or click</div>
+    <div style="font-size:10px;margin-top:2px;color:var(--text-secondary)">Main subject</div>
   `;
   document.getElementById('ref-file-input').value = '';
 }
 
+function handlePoseImage(input) {
+  if (input.files[0]) {
+    poseImageFile = input.files[0];
+    showPosePreview(poseImageFile);
+  }
+}
+
+function showPosePreview(file) {
+  const zone = document.getElementById('pose-drop-zone');
+  zone.classList.add('has-file');
+  const reader = new FileReader();
+  reader.onload = e => {
+    zone.innerHTML = `
+      <img src="${e.target.result}" style="max-height:100px;max-width:100%;border-radius:4px">
+      <div style="margin-top:4px;font-size:11px">${file.name.substring(0,15)}${file.name.length > 15 ? '...' : ''}</div>
+      <button class="btn btn-secondary btn-small" onclick="event.stopPropagation();clearPoseImage()" style="margin-top:4px;padding:2px 8px;font-size:10px">Remove</button>
+    `;
+  };
+  reader.readAsDataURL(file);
+}
+
+function clearPoseImage() {
+  poseImageFile = null;
+  const zone = document.getElementById('pose-drop-zone');
+  zone.classList.remove('has-file');
+  zone.innerHTML = `
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" style="width:28px;height:28px;opacity:0.5;margin-bottom:6px"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+    <div style="font-size:12px">Drop or click</div>
+    <div style="font-size:10px;margin-top:2px;color:var(--text-secondary)">Pose or style</div>
+  `;
+  document.getElementById('pose-file-input').value = '';
+}
+
 function handleVideoImage(input) {
   if (input.files[0]) {
     videoImageFile = input.files[0];
@@ -2158,6 +2217,10 @@ async function doGenerate() {
       }
       const formData = new FormData();
       formData.append('image', refImageFile);
+      // Add pose/style reference image if provided (for multi-ref models)
+      if (poseImageFile) {
+        formData.append('image2', poseImageFile);
+      }
       formData.append('positive_prompt', document.getElementById('gen-positive').value || '');
       formData.append('negative_prompt', document.getElementById('gen-negative').value || '');
       formData.append('content_rating', selectedRating);

src/content_engine/services/cloud_providers/wavespeed_provider.py

@@ -103,6 +103,9 @@ EDIT_MODEL_MAP = {
     # SeeDream Edit (ByteDance) - NSFW OK
     "seedream-4.5-edit": "bytedance/seedream-v4.5/edit",
     "seedream-4-edit": "bytedance/seedream-v4/edit",
+    # SeeDream Multi-Image (Character Consistency across images)
+    "seedream-4.5-multi": "bytedance/seedream-v4.5/edit-sequential",
+    "seedream-4-multi": "bytedance/seedream-v4/edit-sequential",
     # WAN Edit (Alibaba)
     "wan-2.6-edit": "alibaba/wan-2.6/image-edit",
     "wan-2.5-edit": "alibaba/wan-2.5/image-edit",
@@ -126,6 +129,27 @@ EDIT_MODEL_MAP = {
     "default": "bytedance/seedream-v4.5/edit",
 }
 
+# Models that support multiple reference images
+MULTI_REF_MODELS = {
+    # SeeDream Sequential (up to 3 images for character consistency)
+    "seedream-4.5-multi": "bytedance/seedream-v4.5/edit-sequential",
+    "seedream-4-multi": "bytedance/seedream-v4/edit-sequential",
+    # Kling O1 (up to 10 reference images)
+    "kling-o1-multi": "kwaivgi/kling-o1/image-to-image",
+    # Qwen Multi-Angle (multiple angles of same subject)
+    "qwen-multi-angle": "wavespeed-ai/qwen-image/edit-multiple-angles",
+}
+
+# Reference-to-Video models (character + pose reference)
+REF_TO_VIDEO_MAP = {
+    # WAN 2.6 Reference-to-Video (multi-view identity consistency)
+    "wan-2.6-ref": "alibaba/wan-2.6/reference-to-video",
+    "wan-2.6-ref-flash": "alibaba/wan-2.6/reference-to-video-flash",
+    # Kling O3 Reference-to-Video
+    "kling-o3-ref": "kwaivgi/kling-video-o3-pro/reference-to-video",
+    "kling-o3-std-ref": "kwaivgi/kling-video-o3-std/reference-to-video",
+}
+
 WAVESPEED_API_BASE = "https://api.wavespeed.ai/api/v3"
 
 
@@ -153,6 +177,9 @@ class WaveSpeedProvider(CloudProvider):
         """Resolve a friendly name to a WaveSpeed edit model API path."""
         if model_name and model_name in EDIT_MODEL_MAP:
             return EDIT_MODEL_MAP[model_name]
+        # Check multi-reference models
+        if model_name and model_name in MULTI_REF_MODELS:
+            return MULTI_REF_MODELS[model_name]
         if model_name:
             return model_name
         return EDIT_MODEL_MAP["default"]
@@ -430,23 +457,38 @@ class WaveSpeedProvider(CloudProvider):
         *,
         prompt: str,
         image_bytes: bytes,
+        image_bytes_2: bytes | None = None,
         model: str | None = None,
         size: str | None = None,
     ) -> CloudGenerationResult:
-        """Full edit flow: upload image to temp host, call edit API, download result."""
+        """Full edit flow: upload image(s) to temp host, call edit API, download result.
+
+        Args:
+            prompt: The edit prompt
+            image_bytes: Primary reference image (character/subject)
+            image_bytes_2: Optional second reference image (pose/style reference)
+            model: Model name (some models support multiple references)
+            size: Output size (widthxheight)
+        """
         start = time.time()
 
         # WaveSpeed edit APIs require minimum image size (3686400 pixels = ~1920x1920)
         # Auto-upscale small images to meet the requirement
         image_bytes = self._ensure_min_image_size(image_bytes, min_pixels=3686400)
 
-        # Upload reference image to a public URL
-        image_url = await self._upload_temp_image(image_bytes)
+        # Upload reference image(s) to public URLs
+        image_urls = [await self._upload_temp_image(image_bytes)]
+
+        # Upload second reference if provided (for multi-ref models)
+        if image_bytes_2:
+            image_bytes_2 = self._ensure_min_image_size(image_bytes_2, min_pixels=3686400)
+            image_urls.append(await self._upload_temp_image(image_bytes_2))
+            logger.info("Multi-reference edit: uploading 2 images for model=%s", model)
 
         # Submit edit job
         job_id = await self.submit_edit(
             prompt=prompt,
-            image_urls=[image_url],
+            image_urls=image_urls,
             model=model,
             size=size,
         )