Capability · Ghost mannequin

Ghost mannequin API do zdjęć produktowych typu hollow-man

W jednym zdaniu

API ghost mannequin od Photta pobiera zdjęcie odzieży na manekinie i zwraca obraz typu duch z zrekonstruowanym wnętrzem ubrania. Wybierz styl 3d lub flat_lay, wyślij POST, wykonuj polling co 3 sekundy i pobierz po zakończeniu.

  • Typowy czas: 1.5–4 min
  • Credits: 4 credits w 2K · 5 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
Przykładowy wynik

W skrócie

W skrócie

Endpoint
POST /api/v1/ghost-mannequin
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
1.5–4 min
Credits
4 credits w 2K · 5 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

Parametry żądania

product_image

Typ: stringWymagane

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

Typ: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

Typ: string

Which side product_image represents.

= front

Wartości: frontback
angle

Typ: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

Wartości: straightbackside
style

Typ: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

Wartości: 3dflat_lay
background_color

Typ: string

Background color.

= white

Wartości: whitegraybeigeblack
resolution

Typ: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

Wartości: 2K4K
aspect_ratio

Typ: string

Output aspect ratio. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

Wartości: 3:41:14:39:1616:9
user_instruction

Typ: string

Optional free-form note, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

Typ: string

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. API v1 request fields use snake_case; use brand_label_id.

Błędy

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Jedno zdjęcie wejściowe, jedno wynikowe zdjęcie typu ghost mannequin

Prześlij zdjęcie źródłowe, wybierz styl, wyślij żądanie, odpytuj, pobierz.

  1. Krok 1

    Wygeneruj klucz API

    Ghost mannequin korzysta z tych samych danych uwierzytelniających co każda inna funkcja Photta — jeden klucz, jedno saldo credits.

  2. Krok 2

    Prześlij zdjęcie źródłowe

    Przekaż publiczny adres URL lub URI danych base64 w `product_image`; dodaj `back_image`, jeśli masz widok z tyłu. JPEG, PNG i WebP do 10 MB na obraz.

  3. Krok 3

    Wyślij żądanie POST z zadaniem ghost mannequin

    Wyślij żądanie POST do `/api/v1/ghost-mannequin` z `product_image`, `style` (`3d` lub `flat_lay`) oraz opcjonalnymi `angle`, `background_color`, `resolution`. Polling to jedyny sygnał zakończenia — API nie wysyła webhooków.

  4. Krok 4

    Odpytuj do momentu ukończenia zadania

    Wysyłaj żądanie GET `/api/v1/ghost-mannequin/:id` co 3 sekundy, aż `data.status` przyjmie wartość `completed` lub `failed`; typowy czas realizacji to od 1.5 do 4 minut.

  5. Krok 5

    Pobierz i zapisz

    Wynikiem jest plik PNG z usuniętym manekinem i zrekonstruowanym wnętrzem odzieży. Idealne do zdjęć typu duch na PDP, galerii produktów z efektem 3D oraz wstawek flat-lay.

Pytania zadawane przez programistów przed wdrożeniem ghost mannequin

Czym jest fotografia typu ghost mannequin?

Sposób prezentacji na PDP, w którym odzież wygląda, jakby unosiła się na niewidzialnym ciele, ukazując jednocześnie fason i wewnętrzną konstrukcję. Historycznie składa się ją z wielu ujęć studyjnych; API Photta generuje ją w jednym wywołaniu z pojedynczego zdjęcia na manekinie.

Ile kosztuje ghost mannequin?

4 credits w 2K, 5 credits w 4K — o jeden credit taniej na każdym poziomie niż try-on. Koszt nieudanych zadań jest zwracany automatycznie.

Jaka jest różnica między stylem 3D a flat-lay?

Styl `3d` zachowuje trójwymiarowy kształt ciała manekina — odzież zachowuje objętość, ramiona i rękawy układają się naturalnie, a wnętrze jest rekonstruowane. `flat_lay` spłaszcza odzież do czystego układu 2D, idealnego dla kolekcji kapsułowych lub listingów marketplace wymagających spójnego widoku od przodu.

Czy mogę przetwarzać wiele zdjęć wsadowo?

Tak. Wyślij żądanie POST do `/api/v1/ghost-mannequin/batch` z tablicą obrazów źródłowych. W odpowiedzi otrzymasz identyfikator partii oraz identyfikatory generowania dla poszczególnych elementów. Odpytuj `/api/v1/ghost-mannequin/batch/:id` o stan zbiorczy lub każdy element z osobna.

Czy zachowuje wewnętrzne szwy i metki?

Tak — model rekonstruuje wnętrze odzieży (wnętrze dekoltu, mankietów, podszewkę pasa) zamiast halucynować generyczną powierzchnię. Metki i drukowane etykiety widoczne na oryginalnym zdjęciu są zachowywane, jeśli to możliwe.

Jak odpytywać o wynik?

Wysyłaj GET `/api/v1/ghost-mannequin/:id` co 3 sekundy. Zadania wsadowe odpytują nadrzędny endpoint, który zwraca stan zbiorczy oraz podział na poszczególne elementy.

Powiązane możliwości

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 1.5–4 min
  • 4 credits w 2K · 5 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer