AI Product Photography Studio — Complete guide

Overview

AI Product Photography Studio turns a white-background product photo into professional AI-generated scenes (Flux Kontext Pro via fal.ai or Replicate). The product stays rigorously identical from one scene to the next: only the environment changes. The plugin integrates directly into the WooCommerce product edit screen through a dedicated meta box, and generations run in the background via Action Scheduler.

Requirements

• WordPress 6.4 or higher
• WooCommerce 8.0 or higher (Action Scheduler included)
• PHP 8.1 or higher
• A site reachable over HTTPS — AI providers must be able to download your source images through a public URL
• A fal.ai or Replicate account with an active API key

Installation

1. Download the df-ai-product-photography.zip file from your DataFirefly account.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Select the ZIP, click Install Now, then Activate.
4. A new submenu WooCommerce → AI Photo Studio appears: this is the plugin settings page.

On activation, the plugin checks that PHP 8.1+ and WooCommerce are present. If either condition is not met, activation is refused with a clear message.

Getting an API key

Option A — fal.ai (recommended for production)

1. Create an account on fal.ai.
2. Open the dashboard, then the Keys section.
3. Generate a new key and copy it (format xxxxxxxx-xxxx-...:yyyyyyyy).
4. Add credit to your account (pay-per-use, about €0.04 per image).

Option B — Replicate

1. Create an account on replicate.com.
2. Go to Account → API tokens.
3. Generate a token (format r8_...) and copy it.
4. Add a payment method (about €0.06 per image).

Configuration

Go to WooCommerce → AI Photo Studio. The settings page has four tabs.

AI Provider tab

• Provider selection: pick fal.ai or Replicate via the radio cards. Both use the same Flux Kontext Pro model.
• fal.ai API key / Replicate API token: paste the corresponding key. Only the key of the selected provider is required.
• Test button: checks that a key is present for the chosen provider.

Generation settings tab

• Image ratio: Match source image (default), 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 or 2:3.
• Output format: JPEG (default) or PNG.
• Moderation tolerance: 1 (very strict) to 6 (very permissive). 2 is recommended for e-commerce.
• Guidance: prompt adherence strength, 1 to 10 (fal.ai only). 3.5 by default.
• Auto gallery: when checked, every generated image is immediately added to the product gallery without manual action.

Custom scenes tab

In addition to the 12 built-in scenes, you can declare your own scenes in JSON:

[
  {
    "key": "industrial_loft",
    "label": "Industrial loft",
    "category": "lifestyle",
    "icon": "🏭",
    "description": "Raw metal and concrete setting",
    "prompt": "Place this product in a modern industrial loft setting with exposed brick walls, concrete floor, large factory windows, dramatic natural light"
  }
]

• key: unique lowercase identifier without spaces (required)
• label: name shown in the selector
• category: lifestyle, packshot, context or seasonal
• prompt: English instruction, ideally starting with “Place this product…” (required)

Advanced tab

• Log level: Disabled, Errors only (default) or Verbose. Logs are available in WooCommerce → Status → Logs, source df-ai-product-photography.
• A technical info block shows PHP / WordPress / WooCommerce versions and Action Scheduler availability.

Generating scenes

Open any product in Products → All Products. The 🎨 AI Product Photography Studio meta box appears below the editor. The workflow has three steps:

Step 1 — Source photo

Choose the starting image: either Choose from media library, or Use the featured image which reuses the product’s featured image. A sharp photo on a white or neutral background gives the best results — a recent smartphone is enough.

Step 2 — Scene selection

Tick the scenes you want among the cards, organized by category (Lifestyle, Packshot, Use context, Seasonal). The quick links + All Lifestyle, + All Packshot, Select all and Clear speed up selection. A batch is capped at 20 scenes.

Step 3 — Launch

Optionally add extra instructions (e.g. “warm lighting, autumn colors, magazine style”) applied to all scenes of the batch, then click ✨ Generate scenes.

The right-hand 🖼️ Generations column shows each job’s state in real time: Queued → Sending → Generating → Done or Failed. The status refreshes automatically every 3.5 seconds. Expect roughly 10 to 30 seconds per image.

Using generated images

Each completed image offers three actions:

• + Gallery: adds the image to the WooCommerce product gallery (without overwriting existing images).
• View: opens the full-resolution image in a new tab.
• ×: removes the entry from the list (the image stays in the media library).

All generated images are imported into the WordPress media library with traceability metadata: _df_aipp_generated, _df_aipp_scene (scene name) and _df_aipp_origin_product (origin product). You can find and reuse them freely.

How it works technically

Generations are asynchronous: on Generate, the plugin creates one job per scene and schedules it via Action Scheduler (hook df_aipp_submit_job). Each job submits the request to the provider, retrieves an identifier, then a second hook (df_aipp_poll_job) polls the status every 5 seconds, up to 60 attempts (~5 minutes). On transient network errors, the job is retried up to 3 times before being marked as failed.

You can observe and re-run actions in WooCommerce → Status → Scheduled Actions, group df-ai-product-photography.

Troubleshooting

The Generate button is greyed out

The selected provider has no API key configured. Go to WooCommerce → AI Photo Studio → AI Provider and paste your key.

Jobs stay stuck in “Queued”

Action Scheduler is not running. Check that WP-Cron works (visit the site front-end, or configure a real server cron hitting wp-cron.php). Check WooCommerce → Status → Scheduled Actions for pending actions.

“Source image not found” error or immediate failure

The provider cannot download your image. Common causes: local site not publicly accessible, htpasswd protection, server-level hotlink protection, or a CDN blocking external requests. Test the image URL in a private browsing window.

401 / 403 error returned by the provider

Invalid or expired API key, or account without credit. Regenerate the key on the provider dashboard and check your balance.

Generation completes but the image is rejected (safety)

The model flagged the content as sensitive. Increase the Moderation tolerance in the settings (try 3 or 4), or rephrase your custom scene prompt.

Where are the detailed logs?

Set the Log level to Verbose in the Advanced tab, re-run a generation, then check WooCommerce → Status → Logs and pick the df-ai-product-photography source.

Uninstall

Deactivation alone removes nothing. Deleting the plugin triggers uninstall.php, which removes global settings, job metadata on products and remaining scheduled actions. Generated images already in the media library are kept.

FAQ

Can I use both providers in parallel?

The active provider is global (one at a time), but you can switch at any moment in the settings: new generations will use the newly selected provider.

Are generated images royalty-free?

Per fal.ai and Replicate terms, outputs generated with your account belong to you and are commercially usable. Check your provider’s ToS for your specific use case.

Does the plugin work with variable products?

Yes. The meta box is available on all WooCommerce product types. Images are attached to the parent product gallery.