feat(image-to-image): add image-to-image generation

- [feat] Implement `generate_image_to_image` for core generation logic and error handling (image_handler.py:153-296)
- [feat] Add `handle_image_to_image_generation` function for UI input processing (image_handler.py:299-318)
- [add] Define `DEFAULT_IMAGE_TO_IMAGE_MODEL`, `PROVIDER`, `MODEL_PRESETS`, and `EXAMPLE_PROMPTS` (utils.py:12-13,56-61,71-79)
- [feat] Create `create_image_to_image_tab` for Gradio UI, including presets and examples (ui_components.py:7-8,282-459)
- [feat] Integrate new image-to-image tab into the main Gradio interface (app.py:6,9,create_app():33-34)
- [docs] Update main header and footer with image-to-image feature description and tips (ui_components.py:create_main_header():470-471,create_footer():487-495)

app.py

@@ -5,11 +5,12 @@ A comprehensive AI platform with chat and image generation capabilities.
 
 import gradio as gr
 from chat_handler import handle_chat_submit, handle_chat_retry
-from image_handler import handle_image_generation
+from image_handler import handle_image_generation, handle_image_to_image_generation
 from ui_components import (
     create_main_header,
     create_chat_tab,
     create_image_tab,
+    create_image_to_image_tab,
     create_footer
 )
 from utils import get_gradio_theme
@@ -31,6 +32,9 @@ def create_app():
             
             # Image generation tab  
             create_image_tab(handle_image_generation)
+            
+            # Image-to-image tab
+            create_image_to_image_tab(handle_image_to_image_generation)
         
         # Footer with helpful information
         create_footer()

image_handler.py

@@ -153,6 +153,147 @@ def generate_image(
         return None, format_error_message("Unexpected Error", f"An unexpected error occurred: {error_msg}")
 
 
+def generate_image_to_image(
+    input_image,
+    prompt: str,
+    model_name: str,
+    provider: str,
+    negative_prompt: str = "",
+    num_inference_steps: int = IMAGE_CONFIG["num_inference_steps"],
+    guidance_scale: float = IMAGE_CONFIG["guidance_scale"],
+    seed: int = IMAGE_CONFIG["seed"],
+):
+    """
+    Generate an image using image-to-image generation with the specified model and provider through HF-Inferoxy.
+    """
+    # Validate proxy API key
+    is_valid, error_msg = validate_proxy_key()
+    if not is_valid:
+        return None, error_msg
+    
+    proxy_api_key = os.getenv("PROXY_KEY")
+    
+    token_id = None
+    try:
+        # Get token from HF-Inferoxy proxy server with timeout handling
+        print(f"🔑 Image-to-Image: Requesting token from proxy...")
+        token, token_id = get_proxy_token(api_key=proxy_api_key)
+        print(f"✅ Image-to-Image: Got token: {token_id}")
+        
+        print(f"🎨 Image-to-Image: Using model='{model_name}', provider='{provider}'")
+        
+        # Create client with specified provider
+        client = InferenceClient(
+            provider=provider,
+            api_key=token
+        )
+        
+        print(f"🚀 Image-to-Image: Client created, preparing generation params...")
+        
+        # Prepare generation parameters
+        generation_params = {
+            "input_image": input_image,
+            "prompt": prompt,
+            "num_inference_steps": num_inference_steps,
+            "guidance_scale": guidance_scale,
+        }
+        
+        # Add optional parameters if provided
+        if negative_prompt:
+            generation_params["negative_prompt"] = negative_prompt
+        if seed != -1:
+            generation_params["seed"] = seed
+        
+        print(f"📡 Image-to-Image: Making generation request with {IMAGE_GENERATION_TIMEOUT}s timeout...")
+        
+        # Create generation function for timeout handling
+        def generate_image_task():
+            return client.image_to_image(**generation_params)
+        
+        # Execute with timeout using ThreadPoolExecutor
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(generate_image_task)
+            
+            try:
+                # Generate image with timeout
+                image = future.result(timeout=IMAGE_GENERATION_TIMEOUT)
+            except FutureTimeoutError:
+                future.cancel()  # Cancel the running task
+                raise TimeoutError(f"Image-to-image generation timed out after {IMAGE_GENERATION_TIMEOUT} seconds")
+        
+        print(f"🖼️ Image-to-Image: Generation completed! Image type: {type(image)}")
+        
+        # Report successful token usage
+        if token_id:
+            report_token_status(token_id, "success", api_key=proxy_api_key)
+        
+        return image, format_success_message("Image-to-image generated", f"using {model_name} on {provider}")
+        
+    except ConnectionError as e:
+        # Handle proxy connection errors
+        error_msg = f"Cannot connect to HF-Inferoxy server: {str(e)}"
+        print(f"🔌 Image-to-Image connection error: {error_msg}")
+        if token_id:
+            report_token_status(token_id, "error", error_msg, api_key=proxy_api_key)
+        return None, format_error_message("Connection Error", "Unable to connect to the proxy server. Please check if it's running.")
+        
+    except TimeoutError as e:
+        # Handle timeout errors
+        error_msg = f"Image-to-image generation timed out: {str(e)}"
+        print(f"⏰ Image-to-Image timeout: {error_msg}")
+        if token_id:
+            report_token_status(token_id, "error", error_msg, api_key=proxy_api_key)
+        return None, format_error_message("Timeout Error", f"Image-to-image generation took too long (>{IMAGE_GENERATION_TIMEOUT//60} minutes). Try reducing steps.")
+        
+    except HfHubHTTPError as e:
+        # Handle HuggingFace API errors
+        error_msg = str(e)
+        print(f"🤗 Image-to-Image HF error: {error_msg}")
+        if token_id:
+            report_token_status(token_id, "error", error_msg, api_key=proxy_api_key)
+        
+        # Provide more user-friendly error messages
+        if "401" in error_msg:
+            return None, format_error_message("Authentication Error", "Invalid or expired API token. The proxy will provide a new token on retry.")
+        elif "402" in error_msg:
+            return None, format_error_message("Quota Exceeded", "API quota exceeded. The proxy will try alternative providers.")
+        elif "429" in error_msg:
+            return None, format_error_message("Rate Limited", "Too many requests. Please wait a moment and try again.")
+        elif "content policy" in error_msg.lower() or "safety" in error_msg.lower():
+            return None, format_error_message("Content Policy", "Image prompt was rejected by content policy. Please try a different prompt.")
+        else:
+            return None, format_error_message("HuggingFace API Error", error_msg)
+        
+    except Exception as e:
+        # Handle all other errors
+        error_msg = str(e)
+        print(f"❌ Image-to-Image unexpected error: {error_msg}")
+        if token_id:
+            report_token_status(token_id, "error", error_msg, api_key=proxy_api_key)
+        return None, format_error_message("Unexpected Error", f"An unexpected error occurred: {error_msg}")
+
+
+def handle_image_to_image_generation(input_image_val, prompt_val, model_val, provider_val, negative_prompt_val, steps_val, guidance_val, seed_val):
+    """
+    Handle image-to-image generation request with validation.
+    """
+    # Validate input image
+    if input_image_val is None:
+        return None, format_error_message("Validation Error", "Please upload an input image")
+    
+    # Generate image-to-image
+    return generate_image_to_image(
+        input_image=input_image_val,
+        prompt=prompt_val,
+        model_name=model_val,
+        provider=provider_val,
+        negative_prompt=negative_prompt_val,
+        num_inference_steps=steps_val,
+        guidance_scale=guidance_val,
+        seed=seed_val
+    )
+
+
 def handle_image_generation(prompt_val, model_val, provider_val, negative_prompt_val, width_val, height_val, steps_val, guidance_val, seed_val):
     """
     Handle image generation request with validation.

ui_components.py

@@ -6,8 +6,9 @@ Contains functions to create different sections of the Gradio interface.
 import gradio as gr
 from utils import (
     DEFAULT_CHAT_MODEL, DEFAULT_IMAGE_MODEL, DEFAULT_IMAGE_PROVIDER,
+    DEFAULT_IMAGE_TO_IMAGE_MODEL, DEFAULT_IMAGE_TO_IMAGE_PROVIDER,
     CHAT_CONFIG, IMAGE_CONFIG, IMAGE_PROVIDERS, IMAGE_MODEL_PRESETS,
-    IMAGE_EXAMPLE_PROMPTS
+    IMAGE_TO_IMAGE_MODEL_PRESETS, IMAGE_EXAMPLE_PROMPTS, IMAGE_TO_IMAGE_EXAMPLE_PROMPTS
 )
 
 
@@ -282,6 +283,154 @@ def create_image_tab(handle_image_generation_fn):
         gen_event.then(lambda: gr.update(visible=False), None, [stop_generate_btn], queue=False)
 
 
+def create_image_to_image_tab(handle_image_to_image_generation_fn):
+    """
+    Create the image-to-image tab interface.
+    """
+    with gr.Tab("🖼️ Image-to-Image", id="image-to-image"):
+        with gr.Row():
+            with gr.Column(scale=1):
+                # Input image
+                input_image = gr.Image(
+                    label="Input Image", 
+                    type="pil",
+                    height=400,
+                    show_download_button=True
+                )
+                
+                # Model and provider inputs
+                with gr.Group():
+                    gr.Markdown("**🤖 Model & Provider**")
+                    img2img_model_name = gr.Textbox(
+                        value=DEFAULT_IMAGE_TO_IMAGE_MODEL,
+                        label="Model Name",
+                        placeholder="e.g., Qwen/Qwen-Image-Edit or black-forest-labs/FLUX.1-Kontext-dev"
+                    )
+                    img2img_provider = gr.Dropdown(
+                        choices=IMAGE_PROVIDERS,
+                        value=DEFAULT_IMAGE_TO_IMAGE_PROVIDER,
+                        label="Provider",
+                        interactive=True
+                    )
+            
+            with gr.Column(scale=1):
+                # Output image
+                output_image = gr.Image(
+                    label="Generated Image", 
+                    type="pil",
+                    height=400,
+                    show_download_button=True
+                )
+                status_text = gr.Textbox(
+                    label="Generation Status", 
+                    interactive=False,
+                    lines=2
+                )
+            
+            with gr.Column(scale=1):
+                # Generation parameters
+                with gr.Group():
+                    gr.Markdown("**📝 Prompts**")
+                    img2img_prompt = gr.Textbox(
+                        value=IMAGE_TO_IMAGE_EXAMPLE_PROMPTS[0],  # Use first example as default
+                        label="Prompt",
+                        lines=3,
+                        placeholder="Describe how you want to modify the image..."
+                    )
+                    img2img_negative_prompt = gr.Textbox(
+                        value=IMAGE_CONFIG["negative_prompt"],
+                        label="Negative Prompt",
+                        lines=2,
+                        placeholder="Describe what you DON'T want in the modified image..."
+                    )
+                
+                with gr.Group():
+                    gr.Markdown("**⚙️ Generation Settings**")
+                    with gr.Row():
+                        img2img_steps = gr.Slider(
+                            minimum=10, maximum=100, value=IMAGE_CONFIG["num_inference_steps"], step=1,
+                            label="Inference Steps", info="More steps = better quality"
+                        )
+                        img2img_guidance = gr.Slider(
+                            minimum=1.0, maximum=20.0, value=IMAGE_CONFIG["guidance_scale"], step=0.5,
+                            label="Guidance Scale", info="How closely to follow prompt"
+                        )
+                    
+                    img2img_seed = gr.Slider(
+                        minimum=-1, maximum=999999, value=IMAGE_CONFIG["seed"], step=1,
+                        label="Seed", info="-1 for random"
+                    )
+                
+                # Generate and Stop buttons
+                with gr.Row():
+                    generate_btn = gr.Button(
+                        "🖼️ Generate Image-to-Image", 
+                        variant="primary", 
+                        size="lg",
+                        scale=2
+                    )
+                    stop_generate_btn = gr.Button("⏹ Stop", variant="secondary", visible=False)
+                
+                # Quick model presets
+                create_image_to_image_presets(img2img_model_name, img2img_provider)
+        
+        # Examples for image-to-image generation
+        create_image_to_image_examples(img2img_prompt)
+        
+        # Connect image-to-image generation events
+        # Show stop immediately when starting generation
+        generate_btn.click(
+            fn=lambda: gr.update(visible=True),
+            inputs=None,
+            outputs=[stop_generate_btn],
+            queue=False
+        )
+
+        gen_event = generate_btn.click(
+            fn=handle_image_to_image_generation_fn,
+            inputs=[
+                input_image, img2img_prompt, img2img_model_name, img2img_provider, img2img_negative_prompt,
+                img2img_steps, img2img_guidance, img2img_seed
+            ],
+            outputs=[output_image, status_text]
+        )
+
+        # Stop current image-to-image generation
+        stop_generate_btn.click(
+            fn=lambda: gr.update(visible=False),
+            inputs=None,
+            outputs=[stop_generate_btn],
+            cancels=[gen_event],
+            queue=False
+        )
+
+        # Hide stop after generation completes
+        gen_event.then(lambda: gr.update(visible=False), None, [stop_generate_btn], queue=False)
+
+
+def create_image_to_image_presets(img2img_model_name, img2img_provider):
+    """Create quick model presets for image-to-image generation."""
+    with gr.Group():
+        gr.Markdown("**🎯 Popular Presets**")
+        
+        for name, model, provider in IMAGE_TO_IMAGE_MODEL_PRESETS:
+            btn = gr.Button(name, size="sm")
+            btn.click(
+                lambda m=model, p=provider: (m, p),
+                outputs=[img2img_model_name, img2img_provider]
+            )
+
+
+def create_image_to_image_examples(img2img_prompt):
+    """Create example prompts for image-to-image generation."""
+    with gr.Group():
+        gr.Markdown("**🌟 Example Prompts**")
+        img2img_examples = gr.Examples(
+            examples=[[prompt] for prompt in IMAGE_TO_IMAGE_EXAMPLE_PROMPTS],
+            inputs=img2img_prompt
+        )
+
+
 def create_image_presets(img_model_name, img_provider):
     """Create quick model presets for image generation."""
     with gr.Group():
@@ -315,6 +464,7 @@ def create_main_header():
     **Features:**
     - 💬 **Smart Chat**: Conversational AI with streaming responses
     - 🎨 **Image Generation**: Text-to-image creation with multiple providers  
+    - 🖼️ **Image-to-Image**: Transform and modify existing images with AI
     - 🔄 **Intelligent Token Management**: Automatic token rotation and error handling
     - 🌐 **Multi-Provider Support**: Works with HF Inference, Cerebras, Cohere, Groq, Together, Fal.ai, and more
     """)
@@ -337,6 +487,13 @@ def create_footer():
     - Experiment with different models and providers for varied styles
     - Higher inference steps = better quality but slower generation
     
+    **Image-to-Image Tab:**
+    - Upload an input image you want to modify
+    - Describe the changes you want to make to the image
+    - Use negative prompts to avoid unwanted modifications
+    - Perfect for style transfers, object additions, and image transformations
+    - Works great with models like Qwen Image Edit and FLUX.1 Kontext
+    
     **Supported Providers:**
     - **fal-ai**: High-quality image generation (default for images)
     - **hf-inference**: Core API with comprehensive model support

utils.py

@@ -10,6 +10,8 @@ import os
 DEFAULT_CHAT_MODEL = "openai/gpt-oss-20b"
 DEFAULT_IMAGE_MODEL = "Qwen/Qwen-Image"
 DEFAULT_IMAGE_PROVIDER = "fal-ai"
+DEFAULT_IMAGE_TO_IMAGE_MODEL = "Qwen/Qwen-Image-Edit"
+DEFAULT_IMAGE_TO_IMAGE_PROVIDER = "fal-ai"
 
 # Chat configuration
 CHAT_CONFIG = {
@@ -56,6 +58,14 @@ IMAGE_MODEL_PRESETS = [
     ("SDXL (HF)", "stabilityai/stable-diffusion-xl-base-1.0", "hf-inference"),
 ]
 
+# Model presets for image-to-image generation
+IMAGE_TO_IMAGE_MODEL_PRESETS = [
+    ("Qwen Image Edit (Fal.ai)", "Qwen/Qwen-Image-Edit", "fal-ai"),
+    ("Qwen Image Edit (Replicate)", "Qwen/Qwen-Image-Edit", "replicate"),
+    ("FLUX.1 Kontext (Nebius)", "black-forest-labs/FLUX.1-Kontext-dev", "nebius"),
+    ("SDXL (HF)", "stabilityai/stable-diffusion-xl-base-1.0", "hf-inference"),
+]
+
 # Example prompts for image generation
 IMAGE_EXAMPLE_PROMPTS = [
     "A majestic dragon flying over a medieval castle, epic fantasy art, detailed, 8k",
@@ -68,6 +78,18 @@ IMAGE_EXAMPLE_PROMPTS = [
     "An astronaut floating in space with Earth in background, photorealistic, stunning"
 ]
 
+# Example prompts for image-to-image generation
+IMAGE_TO_IMAGE_EXAMPLE_PROMPTS = [
+    "Turn the cat into a tiger with stripes and fierce expression",
+    "Make the background a magical forest with glowing mushrooms",
+    "Change the style to vintage comic book with bold colors",
+    "Add a superhero cape and mask to the person",
+    "Transform the building into a futuristic skyscraper",
+    "Make the flowers bloom and add butterflies around them",
+    "Change the weather to a stormy night with lightning",
+    "Add a magical portal in the background with sparkles"
+]
+
 
 def get_proxy_key():
     """Get the proxy API key from environment variables."""