FLUX Kontext Shopify Product Editor

Winner Project - FLUX.1 Kontext AI Hackathon Built by Rafael Cabrera & Christian Cherry (Carnegie Mellon University) Black Forest Labs × Replicate Hackathon - June 21, 2025

An AI-powered product image editor and marketplace automation tool that uses FLUX.1 Kontext to transform product photos with natural language prompts, automatically generates compelling product descriptions using OpenAI's o4-mini, and publishes directly to Shopify.

Features

• AI Image Enhancement: Transform product images using natural language prompts via FLUX.1 Kontext Pro
• Smart Prompt Optimization: Automatically improves your prompts using OpenAI o4-mini for better results
• AI-Generated Descriptions: Creates compelling product descriptions optimized for e-commerce
• Direct Shopify Integration: One-click publishing to your Shopify store
• Iterative Editing: Regenerate descriptions or refine images without starting over
• User-Friendly UI: Built with Gradio for an intuitive experience

How It Works

1. Upload: Start with your product image
2. Describe: Enter how you want to transform it (e.g., "add elegant lighting and a marble background")
3. Enhance: AI optimizes your prompt and generates an improved image using FLUX Kontext
4. Generate: Automatically creates a marketplace-ready product description
5. Publish: One click to publish directly to your Shopify store

Tech Stack

• Image Generation: FLUX.1 Kontext Pro by Black Forest Labs
• Prompt & Description AI: OpenAI o4-mini via Replicate
• UI Framework: Gradio
• E-commerce Integration: Shopify Admin API
• Infrastructure: Replicate API for model hosting

Installation

Prerequisites

• Python 3.8+
• Replicate API key (get one here)
• Shopify store with Admin API access (setup guide)

Setup

1. Clone the repository

   git clone https://github.com/yourusername/flux-kontext-shopify.git
   cd flux-kontext-shopify

2. Install dependencies

   pip install -r requirements.txt

3. Set environment variables

   export REPLICATE_API_TOKEN="your_replicate_token"
   export SHOPIFY_TOKEN="your_shopify_admin_token"

   Or create a .env file:

   REPLICATE_API_TOKEN=your_replicate_token
   SHOPIFY_TOKEN=your_shopify_admin_token
   

4. Update Shopify configuration

   Edit image_chatbot.py line 11 to use your Shopify store URL:

   url = "https://YOUR-STORE.myshopify.com/admin/api/2024-07/products.json"

Usage

Run the Main Application

python image_chatbot.py

This launches the Gradio interface, which will open in your browser. The app includes a shareable link for demos.

Workflow

1. Upload your product image
2. Enter enhancement prompt (e.g., "add warm lighting and place on a wooden surface")
3. Add product title for Shopify
4. Click "Process Image" - the app will:
   • Enhance your prompt using AI
   • Generate an improved product image
   • Create an optimized product description
5. Optional: Click "Re-run Description Only" to regenerate the description
6. Click "Publish to Shopify" to add the product to your store

Alternative Demo: Flask Chat Interface

A simpler chat-style interface for iterative image editing:

cd flux_demo
python app.py

Access at http://localhost:5000

This version allows you to:

• Upload an initial image
• Make multiple edits in sequence
• See the conversation history of all transformations

Project Structure

flux-kontext-shopify/
├── image_chatbot.py          # Main Gradio application
├── flux_demo/
│   ├── app.py               # Flask chat interface alternative
│   ├── templates/
│   │   └── index.html       # Chat UI template
│   └── requirements.txt
├── images/                   # Sample product images
│   ├── drawer.png
│   ├── mattress.png
│   └── table_deconstruction.jpg
├── requirements.txt          # Python dependencies
└── README.md

API Models Used

FLUX.1 Kontext Pro

• Purpose: Image-to-image transformation with natural language
• Parameters:
  • prompt: Natural language description of desired changes
  • input_image: Original product photo
  • aspect_ratio: "match_input_image"
  • safety_tolerance: 2

OpenAI o4-mini

• Purpose: Prompt enhancement and description generation
• Configuration:
  • reasoning_effort: "low" for prompts, "medium" for descriptions
  • Custom system prompts for e-commerce optimization

Configuration

Prompt Enhancement

The app automatically improves your prompts to focus on e-commerce appeal while preserving product characteristics. You can modify the prompt enhancement logic in image_chatbot.py lines 65-75.

Description Generation

Product descriptions are optimized for online marketplaces. Customize the copywriting style in lines 42-56.

Shopify Settings

• API version: 2024-07
• Products published with "active" status by default
• Supports custom vendor and product_type fields

Sample Use Cases

• Furniture sellers: Transform plain product photos with styled backgrounds
• Handmade goods: Add professional staging and lighting
• Vintage items: Modernize presentation while keeping authenticity
• Electronics: Add lifestyle context to technical products

Development Notes

Test Files

The repository includes test files for individual API components:

• flux_test.py, flux_test2.py - FLUX API experiments
• o4_mini_test.py - OpenAI o4-mini testing
• sam2_test.py - Segmentation experiments
• blip_test.py - Image captioning tests

These are used for development and can be safely ignored for production use.

Temporary Files

The app generates temporary files (temp_input_*.png, temp_output_*.jpg) during processing. These can be cleaned up periodically or handled via the .gitignore.

Troubleshooting

Common Issues

"No module named 'replicate'"

pip install replicate gradio pillow requests

Shopify authentication errors

• Verify your Admin API token has write_products permission
• Check that your store URL is correct (include .myshopify.com)

Image generation fails

• Ensure REPLICATE_API_TOKEN is set correctly
• Check you have credits in your Replicate account
• Verify image file is valid and not corrupted

Rate limiting

• FLUX Kontext Pro may take 10-30 seconds per image
• Consider adding retry logic for production use

Credits

Built at the FLUX.1 Kontext AI Hackathon hosted by:

• Black Forest Labs - FLUX.1 Kontext model
• Replicate - API infrastructure and hosting
• Resemble AI - Voice AI platform (prize sponsor)

Team:

• Rafael Cabrera - Carnegie Mellon University
• Christian Cherry - Carnegie Mellon University

License

MIT License - see LICENSE file for details

Acknowledgments

• Black Forest Labs for the incredible FLUX.1 Kontext model
• Replicate for the seamless API and hackathon support
• OpenAI for o4-mini reasoning model
• The Gradio team for the UI framework

Links

• FLUX.1 Kontext on Replicate
• Replicate Platform
• Black Forest Labs
• Hackathon Event

---

Built with FLUX.1 Kontext at the San Francisco AI Hackathon, June 2025