# 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…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/df-ai-product-photography/index.md), [en](https://www.datafirefly.com/en/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), [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)
- Indice:
## 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
**Importante:** i siti in locale (localhost, .test, .local) non funzioneranno: il provider IA non può raggiungere l'URL dell'immagine sorgente. Usa un ambiente di staging pubblicamente accessibile o un tunnel (ngrok, Cloudflare Tunnel).
## 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](https://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](https://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)
**Suggerimento:** scrivi i tuoi prompt in inglese e descrivi l'ambiente, l'illuminazione e lo stile fotografico. Il plugin aggiunge automaticamente una protezione per preservare il prodotto ed evitare testo e watermark.
### 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.