# AI Product Photography Studio: kompletny przewodnik

> Prezentacja AI Product Photography Studio zamienia zdjęcie produktu na białym tle w profesjonalne aranżacje generowane przez AI (Flux Kontext Pro przez fal.ai albo Replicate). Produkt pozostaje rygorystycznie identyczny między scenami:…

- Strona: <https://www.datafirefly.com/pl/documentation/df-ai-product-photography/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [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), [it](https://www.datafirefly.com/it/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)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Prezentacja

AI Product Photography Studio zamienia zdjęcie produktu na białym tle w profesjonalne aranżacje generowane przez AI (Flux Kontext Pro przez fal.ai albo Replicate). Produkt pozostaje rygorystycznie identyczny między scenami: zmienia się wyłącznie otoczenie. Wtyczka integruje się bezpośrednio z kartą produktu WooCommerce przez dedykowany meta box, a generowanie działa w tle dzięki Action Scheduler.

## Wymagania

- WordPress 6.4 lub nowszy
- WooCommerce 8.0 lub nowszy (Action Scheduler w komplecie)
- PHP 8.1 lub nowszy
- Witryna dostępna po HTTPS: dostawcy AI muszą móc pobrać Twoje obrazy źródłowe przez publiczny adres URL
- Konto fal.ai **albo** Replicate z aktywnym kluczem API

**Ważne:** witryny lokalne (localhost, .test, .local) nie zadziałają: dostawca AI nie może dosięgnąć adresu URL obrazu źródłowego. Użyj publicznie dostępnego środowiska staging albo tunelu (ngrok, Cloudflare Tunnel).

## Instalacja

1. Pobierz plik `df-ai-product-photography.zip` ze swojego konta DataFirefly.
2. W WordPressie przejdź do **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**.
3. Wybierz ZIP, kliknij **Zainstaluj teraz**, a następnie **Włącz**.
4. Pojawi się nowe podmenu **WooCommerce → AI Photo Studio**: to strona ustawień wtyczki.

Przy aktywacji wtyczka sprawdza obecność PHP 8.1+ i WooCommerce. Jeśli któryś z warunków nie jest spełniony, aktywacja jest odmawiana z czytelnym komunikatem.

## Uzyskanie klucza API

### Opcja A: fal.ai (zalecane w produkcji)

1. Utwórz konto na [fal.ai](https://fal.ai).
2. Otwórz dashboard, następnie sekcję **Keys**.
3. Wygeneruj nowy klucz i skopiuj go (format `xxxxxxxx-xxxx-...:yyyyyyyy`).
4. Doładuj konto (rozliczenie za zużycie, około 0,04 € za obraz).

### Opcja B: Replicate

1. Utwórz konto na [replicate.com](https://replicate.com).
2. Przejdź do **Account → API tokens**.
3. Wygeneruj token (format `r8_...`) i skopiuj go.
4. Podaj metodę płatności (około 0,06 € za obraz).

## Konfiguracja

Przejdź do **WooCommerce → AI Photo Studio**. Strona ustawień składa się z czterech zakładek.

### Zakładka Dostawca AI

- **Wybór dostawcy**: wybierz fal.ai albo Replicate kartami radio. Oba korzystają z tego samego modelu Flux Kontext Pro.
- **Klucz API fal.ai** / **Token API Replicate**: wklej odpowiedni klucz. Wymagany jest tylko klucz wybranego dostawcy.
- **Przycisk Testuj**: sprawdza, czy klucz dla wybranego dostawcy został wpisany.

### Zakładka Parametry generowania

- **Proporcje obrazu**: `Takie jak źródło` (domyślnie), 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 albo 2:3.
- **Format wyjściowy**: JPEG (domyślnie) albo PNG.
- **Tolerancja moderacji**: od 1 (bardzo restrykcyjnie) do 6 (bardzo liberalnie). Dla e-commerce zalecana wartość 2.
- **Guidance**: siła trzymania się promptu, od 1 do 10 (tylko fal.ai). Domyślnie 3.5.
- **Automatyczna galeria**: po zaznaczeniu każdy wygenerowany obraz jest natychmiast dodawany do galerii produktu bez ręcznej interwencji.

### Zakładka Sceny własne

Oprócz 12 wbudowanych scen możesz zadeklarować własne aranżacje w formacie JSON:

```
[
  {
    "key": "loft_industrialny",
    "label": "Loft industrialny",
    "category": "lifestyle",
    "icon": "🏭",
    "description": "Surowy wystrój, metal i beton",
    "prompt": "Place this product in a modern industrial loft setting with exposed brick walls, concrete floor, large factory windows, dramatic natural light"
  }
]
```

- `key`: unikalny identyfikator małymi literami bez spacji (obowiązkowy)
- `label`: nazwa wyświetlana w selektorze
- `category`: `lifestyle`, `packshot`, `context` albo `seasonal`
- `prompt`: instrukcja po angielsku, najlepiej zaczynająca się od „Place this product..." (obowiązkowa)

**Wskazówka:** pisz prompty po angielsku i opisuj otoczenie, światło i styl fotograficzny. Wtyczka automatycznie dodaje zabezpieczenie chroniące produkt i wykluczające tekst oraz znaki wodne.

### Zakładka Zaawansowane

- **Poziom logów**: Wyłączone, Tylko błędy (domyślnie) albo Verbose. Logi znajdziesz w **WooCommerce → Status → Dzienniki**, źródło `df-ai-product-photography`.
- Blok informacji technicznych pokazuje wersje PHP / WordPressa / WooCommerce i obecność Action Schedulera.

## Generowanie aranżacji

Otwórz dowolny produkt w **Produkty → Wszystkie produkty**. Meta box **🎨 AI Product Photography Studio** pojawia się pod edytorem. Przepływ pracy składa się z trzech kroków:

### Krok 1: zdjęcie źródłowe

Wybierz obraz wyjściowy: przez **Wybierz z biblioteki mediów** albo **Użyj obrazka wyróżniającego**, który pobiera główny obrazek produktu. Ostre zdjęcie na białym albo neutralnym tle daje najlepsze rezultaty; wystarczy nowszy smartfon.

### Krok 2: wybór scen

Zaznacz pożądane aranżacje spośród kart, uporządkowanych w kategorie (Lifestyle, Packshot, Kontekst użycia, Sezonowe). Szybkie linki **+ Wszystkie Lifestyle**, **+ Wszystkie Packshot**, **Zaznacz wszystko** i **Wyczyść** przyspieszają wybór. Jedna partia jest ograniczona do maksymalnie 20 scen.

### Krok 3: uruchomienie

Opcjonalnie dodaj dodatkowe instrukcje (np. „ciepłe oświetlenie, jesienne kolory, styl magazynowy"), które zostaną zastosowane do wszystkich scen partii, a następnie kliknij **✨ Generuj aranżacje**.

Prawa kolumna **🖼️ Generacje** pokazuje stan każdego zadania w czasie rzeczywistym: _W kolejce_ → _Wysyłanie_ → _Generowanie_ → _Zakończone_ albo _Błąd_. Status odświeża się automatycznie co 3,5 sekundy. Licz się zwykle z 10 do 30 sekundami na obraz.

## Wykorzystanie wygenerowanych obrazów

Każdy ukończony obraz oferuje trzy akcje:

- **+ Galeria**: dodaje obraz do galerii produktu WooCommerce (bez nadpisywania istniejących obrazów).
- **Zobacz**: otwiera obraz w pełnej rozdzielczości w nowej karcie.
- **×**: usuwa wpis z listy (obraz pozostaje w bibliotece mediów).

Wszystkie wygenerowane obrazy są importowane do biblioteki mediów WordPressa z metadanymi identyfikacyjnymi: `_df_aipp_generated`, `_df_aipp_scene` (nazwa sceny) i `_df_aipp_origin_product` (produkt źródłowy). Możesz je więc odnaleźć i swobodnie wykorzystywać ponownie.

## Działanie techniczne

Generowanie jest asynchroniczne: po kliknięciu Generuj wtyczka tworzy zadanie per scena i planuje je przez Action Scheduler (hook `df_aipp_submit_job`). Każde zadanie przesyła żądanie do dostawcy, pobiera identyfikator, a drugi hook (`df_aipp_poll_job`) odpytuje status co 5 sekund, do 60 prób (~5 minut). Przy przejściowym błędzie sieci zadanie jest ponawiane do 3 razy, zanim zostanie oznaczone jako nieudane.

Akcje możesz obserwować i wznawiać w **WooCommerce → Status → Zaplanowane akcje**, grupa `df-ai-product-photography`.

## Rozwiązywanie problemów

### Przycisk Generuj jest wyszarzony

Wybrany dostawca nie ma wpisanego klucza API. Przejdź do **WooCommerce → AI Photo Studio → Dostawca AI** i wklej klucz.

### Zadania tkwią w statusie „W kolejce"

Action Scheduler się nie wykonuje. Sprawdź, czy WP-Cron działa (odwiedź witrynę od frontu albo skonfiguruj prawdziwy cron serwerowy wskazujący na `wp-cron.php`). Zajrzyj do **WooCommerce → Status → Zaplanowane akcje**, aby zobaczyć oczekujące akcje.

### Błąd „Nie znaleziono obrazu źródłowego" albo natychmiastowa porażka

Dostawca nie może pobrać Twojego obrazu. Częste przyczyny: witryna lokalna niedostępna publicznie, ochrona htpasswd, ochrona przed hotlinkowaniem na serwerze albo CDN blokujący zewnętrzne żądania. Przetestuj adres URL obrazu w oknie prywatnym przeglądarki.

### Błąd 401 / 403 zwracany przez dostawcę

Klucz API nieprawidłowy, wygasły albo konto bez środków. Zregeneruj klucz w panelu dostawcy i sprawdź saldo.

### Generowanie kończy się, ale obraz jest odrzucany (safety)

Model uznał treść za wrażliwą. Zwiększ **Tolerancję moderacji** w ustawieniach (spróbuj 3 albo 4) albo przeredaguj prompt swojej sceny własnej.

### Gdzie znaleźć szczegółowe logi?

Przełącz **Poziom logów** na Verbose w zakładce Zaawansowane, uruchom generowanie ponownie, a następnie przejdź do **WooCommerce → Status → Dzienniki** i wybierz źródło `df-ai-product-photography`.

## Deinstalacja

Samo wyłączenie niczego nie usuwa. Usunięcie wtyczki uruchamia `uninstall.php`, który kasuje ustawienia globalne, metadane zadań na produktach i pozostałe zaplanowane akcje. Wygenerowane obrazy obecne już w bibliotece mediów są zachowywane.

## FAQ

### Czy mogę używać obu dostawców równolegle?

Aktywny dostawca jest globalny (jeden naraz), ale możesz przełączyć się w każdej chwili w ustawieniach: nowe generacje użyją nowo wybranego dostawcy.

### Czy wygenerowane obrazy są wolne od praw?

Zgodnie z warunkami fal.ai i Replicate wyniki wygenerowane na Twoim koncie należą do Ciebie i mogą być wykorzystywane komercyjnie. Zweryfikuj regulamin swojego dostawcy dla własnego przypadku użycia.

### Czy wtyczka działa z produktami wariantowymi?

Tak. Meta box jest dostępny dla wszystkich typów produktów WooCommerce. Obrazy są dołączane do galerii produktu nadrzędnego.