# 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…

- Page: <https://www.datafirefly.com/en/documentation/df-ai-product-photography/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/df-ai-product-photography/index.md), [es](https://www.datafirefly.com/es/documentation/df-ai-product-photography/index.md), [de](https://www.datafirefly.com/de/documentation/df-ai-product-photography/index.md), [it](https://www.datafirefly.com/it/documentation/df-ai-product-photography/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-ai-product-photography/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-ai-product-photography/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-ai-product-photography/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## 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

**Important:** local sites (localhost, .test, .local) will not work: the AI provider cannot reach your source image URL. Use a publicly accessible staging environment or a tunnel (ngrok, Cloudflare Tunnel).

## 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](https://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](https://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)

**Tip:** write your prompts in English and describe the environment, lighting and photographic style. The plugin automatically appends a safeguard to preserve the product and avoid text and watermarks.

### 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.