AI Product Photography Studio — Guida completa

Panoramica

AI Product Photography Studio trasforma una foto prodotto su sfondo bianco in scene professionali generate dall’IA (Flux Kontext Pro via fal.ai o Replicate). Il prodotto rimane rigorosamente identico da una scena all’altra: cambia solo l’ambiente. Il plugin si integra direttamente nella scheda prodotto WooCommerce tramite una meta box dedicata, e le generazioni vengono eseguite in background grazie ad Action Scheduler.

Requisiti

• WordPress 6.4 o superiore
• WooCommerce 8.0 o superiore (Action Scheduler incluso)
• PHP 8.1 o superiore
• Un sito raggiungibile via HTTPS — i provider IA devono poter scaricare le immagini sorgente tramite un URL pubblico
• Un account fal.ai o Replicate con una chiave API attiva

Installazione

1. Scarica il file df-ai-product-photography.zip dal tuo account DataFirefly.
2. In WordPress, vai su Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona il ZIP, clicca su Installa ora, poi su Attiva.
4. Appare un nuovo sottomenu WooCommerce → AI Photo Studio: è la pagina delle impostazioni del plugin.

All’attivazione, il plugin verifica che PHP 8.1+ e WooCommerce siano presenti. Se una condizione non è soddisfatta, l’attivazione viene rifiutata con un messaggio chiaro.

Ottenere una chiave API

Opzione A — fal.ai (consigliato in produzione)

1. Crea un account su fal.ai.
2. Apri il dashboard, poi la sezione Keys.
3. Genera una nuova chiave e copiala (formato xxxxxxxx-xxxx-...:yyyyyyyy).
4. Aggiungi credito al tuo account (pagamento a consumo, circa 0,04 € per immagine).

Opzione B — Replicate

1. Crea un account su replicate.com.
2. Vai su Account → API tokens.
3. Genera un token (formato r8_...) e copialo.
4. Inserisci un metodo di pagamento (circa 0,06 € per immagine).

Configurazione

Vai su WooCommerce → AI Photo Studio. La pagina delle impostazioni ha quattro schede.

Scheda Provider IA

• Scelta del provider: seleziona fal.ai o Replicate tramite le card radio. Entrambi usano lo stesso modello Flux Kontext Pro.
• Chiave API fal.ai / Token API Replicate: incolla la chiave corrispondente. È richiesta solo la chiave del provider selezionato.
• Pulsante Prova: verifica che la chiave sia presente per il provider scelto.

Scheda Parametri di generazione

• Rapporto immagine: Come la sorgente (default), 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 o 2:3.
• Formato di output: JPEG (default) o PNG.
• Tolleranza moderazione: da 1 (molto rigido) a 6 (molto permissivo). 2 è consigliato per l’e-commerce.
• Guidance: aderenza al prompt, da 1 a 10 (solo fal.ai). 3,5 di default.
• Galleria automatica: se spuntato, ogni immagine generata viene aggiunta immediatamente alla galleria del prodotto senza intervento manuale.

Scheda Scene personalizzate

Oltre alle 12 scene integrate, puoi dichiarare le tue scene in JSON:

[
  {
    "key": "loft_industriale",
    "label": "Loft industriale",
    "category": "lifestyle",
    "icon": "🏭",
    "description": "Ambientazione grezza metallo e cemento",
    "prompt": "Place this product in a modern industrial loft setting with exposed brick walls, concrete floor, large factory windows, dramatic natural light"
  }
]

• key: identificatore univoco in minuscolo senza spazi (obbligatorio)
• label: nome mostrato nel selettore
• category: lifestyle, packshot, context o seasonal
• prompt: istruzione in inglese, idealmente iniziando con “Place this product…” (obbligatorio)

Scheda Avanzato

• Livello di log: Disattivato, Solo errori (default) o Dettagliato. I log si consultano in WooCommerce → Stato → Log, sorgente df-ai-product-photography.
• Un blocco di informazioni tecniche mostra le versioni PHP / WordPress / WooCommerce e la presenza di Action Scheduler.

Generare scene

Apri qualsiasi prodotto in Prodotti → Tutti i prodotti. La meta box 🎨 AI Product Photography Studio appare sotto l’editor. Il flusso di lavoro ha tre passaggi:

Passo 1 — Foto sorgente

Scegli l’immagine di partenza: tramite Scegli dalla libreria multimediale, o tramite Usa l’immagine in evidenza che riutilizza l’immagine in evidenza del prodotto. Una foto nitida su sfondo bianco o neutro dà i migliori risultati — uno smartphone recente basta.

Passo 2 — Selezione delle scene

Spunta le scene desiderate tra le card, organizzate per categoria (Lifestyle, Packshot, Contesto d’uso, Stagionale). I link rapidi + Tutte Lifestyle, + Tutte Packshot, Seleziona tutto e Svuota accelerano la selezione. Un batch è limitato a 20 scene.

Passo 3 — Avvio

Aggiungi eventualmente istruzioni aggiuntive (es. «luce calda, colori autunnali, stile magazine») applicate a tutte le scene del batch, poi clicca su ✨ Genera scene.

La colonna destra 🖼️ Generazioni mostra lo stato di ogni job in tempo reale: In coda → Invio → Generazione → Completato o Fallito. Lo stato si aggiorna automaticamente ogni 3,5 secondi. Conta generalmente da 10 a 30 secondi per immagine.

Usare le immagini generate

Ogni immagine completata offre tre azioni:

• + Galleria: aggiunge l’immagine alla galleria del prodotto WooCommerce (senza sovrascrivere le immagini esistenti).
• Vedi: apre l’immagine a piena risoluzione in una nuova scheda.
• ×: rimuove la voce dalla lista (l’immagine resta nella libreria multimediale).

Tutte le immagini generate vengono importate nella libreria multimediale WordPress con metadati di tracciabilità: _df_aipp_generated, _df_aipp_scene (nome della scena) e _df_aipp_origin_product (prodotto di origine). Puoi ritrovarle e riutilizzarle liberamente.

Funzionamento tecnico

Le generazioni sono asincrone: al clic su Genera, il plugin crea un job per scena e lo pianifica via Action Scheduler (hook df_aipp_submit_job). Ogni job invia la richiesta al provider, ottiene un identificatore, poi un secondo hook (df_aipp_poll_job) interroga lo stato ogni 5 secondi, fino a 60 tentativi (~5 minuti). In caso di errore di rete transitorio, il job viene ritentato fino a 3 volte prima di essere segnato come fallito.

Puoi osservare e rilanciare le azioni in WooCommerce → Stato → Azioni pianificate, gruppo df-ai-product-photography.

Risoluzione dei problemi

Il pulsante Genera è disabilitato

Il provider selezionato non ha una chiave API configurata. Vai su WooCommerce → AI Photo Studio → Provider IA e incolla la tua chiave.

I job restano bloccati in «In coda»

Action Scheduler non è in esecuzione. Verifica che WP-Cron funzioni (visita il sito lato front, o configura un vero cron di server puntato su wp-cron.php). Consulta WooCommerce → Stato → Azioni pianificate per vedere le azioni in attesa.

Errore «Immagine sorgente non trovata» o fallimento immediato

Il provider non riesce a scaricare la tua immagine. Cause frequenti: sito locale non accessibile pubblicamente, protezione htpasswd, hotlink protection a livello server o un CDN che blocca le richieste esterne. Prova l’URL dell’immagine in una finestra di navigazione privata.

Errore 401 / 403 restituito dal provider

Chiave API non valida, scaduta o account senza credito. Rigenera la chiave sul dashboard del provider e verifica il tuo saldo.

La generazione termina ma l’immagine viene rifiutata (safety)

Il modello ha giudicato il contenuto sensibile. Aumenta la Tolleranza moderazione nelle impostazioni (prova 3 o 4), o riformula il prompt della tua scena personalizzata.

Dove trovo i log dettagliati?

Imposta il Livello di log su Dettagliato nella scheda Avanzato, rilancia una generazione, poi consulta WooCommerce → Stato → Log selezionando la sorgente df-ai-product-photography.

Disinstallazione

La sola disattivazione non elimina nulla. L’eliminazione del plugin esegue uninstall.php, che rimuove le impostazioni globali, i metadati dei job sui prodotti e le azioni pianificate rimanenti. Le immagini generate già presenti nella libreria multimediale vengono conservate.

FAQ

Posso usare entrambi i provider in parallelo?

Il provider attivo è globale (uno alla volta), ma puoi cambiare in qualsiasi momento nelle impostazioni: le nuove generazioni useranno il provider appena selezionato.

Le immagini generate sono libere da diritti?

Secondo le condizioni di fal.ai e Replicate, gli output generati con il tuo account ti appartengono e sono utilizzabili commercialmente. Verifica i termini del tuo provider per il tuo caso d’uso.

Il plugin funziona con i prodotti variabili?

Sì. La meta box è disponibile su tutti i tipi di prodotto WooCommerce. Le immagini vengono allegate alla galleria del prodotto padre.