Główne procesy

Ta strona zbiera wszystkie obsługiwane przebiegi integracji w pigułce. Każdy proces ma swój samouczek z gotowymi do skopiowania wywołaniami curl — zacznij od tego, który odpowiada Twojej sytuacji.

Zanim zaczniesz: każdy przebieg wymaga instalacji wtyczki i powiązanego z nią klucza API — zobacz Uwierzytelnianie, gdzie opisaliśmy konfigurację krok po kroku.

Dwa pojęcia, które wystarczą na start:

• Sesja (zamówienie) — jedno wywołanie POST /jobs: wspólna konfiguracja (styl, sceneria, modelka, proporcje) zastosowana do jednego lub wielu produktów. Identyfikowana przez order_id.
• Packshot — zdjęcie produktu na czystym, neutralnym tle. Sesję zdjęciową można zamówić tylko dla produktu, który ma zaakceptowany packshot.

Pełny słowniczek znajdziesz na stronie przeglądu.

A. Sesja zdjęciowa z gotowego packshota

Najkrótsza droga do gotowych zdjęć: sprzedawca ma już packshot produktu, więc wgrywasz go, rejestrujesz i od razu zamawiasz sesję.

1. POST /assets/upload      → tymczasowy adres do wgrania pliku
2. PUT <upload_url>         → wyślij plik packshota
3. POST /packshots          → zarejestruj packshot (zaakceptowany od razu)
4. POST /jobs               → zamów sesję zdjęciową
5. webhook / GET /jobs/{id} → odbierz gotowe zdjęcia
6. POST /jobs/{id}/accept   → (opcjonalnie) oceń wyniki

Samouczek: sesja z gotowego packshota →

B. Packshot ze zwykłego zdjęcia ze sklepu

Sprzedawca ma tylko zwykłe zdjęcie produktu (np. z aparatu telefonu). Najpierw generujesz kilka propozycji packshota, sprzedawca wybiera jedną, a po jej zaakceptowaniu możesz zamawiać sesje zdjęciowe. To tu działa wymóg zaakceptowanego packshota: sesja dla produktu bez zaakceptowanego packshota zwraca błąd 422 packshot_not_approved.

1. POST /assets/upload + PUT      → wgraj zdjęcie ze sklepu
2. POST /images                   → zarejestruj zdjęcie w katalogu
3. POST /jobs (job_type=packshot) → zamów N propozycji packshota
4. POST /jobs/{id}/accept         → zaakceptuj wybraną propozycję
   POST /jobs/{id}/reject         → odrzuć pozostałe
5. POST /jobs                     → zamów sesję zdjęciową

Samouczek: packshot ze zdjęcia →

C. Parametry sesji — styl, sceneria, modelka

Zanim wyślesz sesję, pokaż sprzedawcy, co może wybrać. Pięć endpointów zwraca kompletny katalog: style (presety) z miniaturami i galeriami, modelki, scenerie, dostępne modele AI z kosztami w kredytach oraz proporcje obrazu. Z tych danych zbudujesz ekran wyboru w swojej wtyczce.

GET /presets        → style z miniaturami, galeriami i kosztem
GET /models         → modelki (konto + marketplace)
GET /sceneries      → scenerie (konto + marketplace)
GET /ai-models      → modele AI dostępne dla planu konta
GET /aspect-ratios  → proporcje obrazu (jedna domyślna)

Samouczek: parametry sesji →

D. Wiele produktów naraz

Masz do obfotografowania cały asortyment? Jedna sesja przyjmuje do 100 produktów, a POST /jobs/batch — do 100 sesji w jednym wywołaniu (łącznie do 5000 zdjęć). Odpowiedź to HTTP 207: każda sesja przechodzi albo odpada niezależnie od pozostałych.

1. Przygotuj sesje (produkty + konfiguracja)
2. POST /jobs/batch  → do 100 sesji naraz
3. HTTP 207          → wynik per sesja (accepted / failed)
4. Odbierz wyniki przez webhooki lub odpytywanie

Samouczek: sesje hurtowo →

E. Odbieranie wyników

Gdy zadanie się kończy, wysyłamy webhook na adres Twojej instalacji — z podpisem HMAC, automatycznymi ponowieniami i możliwością ponownej wysyłki. Jeśli nie chcesz utrzymywać endpointu webhook, możesz odpytywać GET /jobs/{id}. Adresy pobierania wyników są ważne co najmniej 7 dni; świeży adres uzyskasz jednym wywołaniem.

webhook (push)                  GET /jobs/{id} (pull)
  ├─ zweryfikuj podpis HMAC       ├─ sprawdzaj status
  ├─ odpowiedz 2xx                └─ pobierz outputs[].url
  └─ pobierz outputs[].url
wygasł adres? → POST /jobs/{id}/refresh-url

Samouczek: odbieranie wyników →

F. Ponowna sesja (regeneracja)

Sprzedawca chce więcej zdjęć w tym samym stylu albo nie jest zadowolony z poprzedniej rundy? Sklonuj sesję jednym wywołaniem — ta sama konfiguracja, opcjonalnie inna liczba zdjęć per produkt. Klon to świeży start: oceny nie przechodzą, kredyty są naliczane od nowa.

1. POST /orders/{id}/clone  (nagłówek Idempotency-Key wymagany)
   ├─ puste body            → te same produkty i liczby zdjęć
   └─ body z subjects[]     → nowe liczby zdjęć per produkt
2. Odbierz wyniki jak w procesie E

Samouczek: ponowna sesja →

Co dalej

• Uwierzytelnianie — klucze API i uprawnienia, zanim zaczniesz.
• Endpointy — pełna lista tras, gdy znasz już procesy.
• Lista błędów — każdy kod błędu z przyczyną i sposobem naprawy.