Ominaisuus · Ghost mannequin

Ghost mannequin API näkymättömän mallinuken tuotekuviin

Yhdellä lauseella

Phottan ghost mannequin API ottaa kuvan vaatteesta nuken päällä ja palauttaa näkymätön nukke -kuvan, jossa vaatteen sisäosa on rekonstruoitu. Valitse tyyliksi 3d tai flat_lay, tee POST, pollaa 3 sekunnin välein ja lataa tilassa completed.

  • Tyypillinen kesto: 1.5–4 min
  • Credits: 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • Käsittely: asynkroninen, polling
  • Rajoitukset: 600 pyyntöä/min
  • Autentikointi: Bearer-avain

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

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
Esimerkkitulos

Lyhyesti

Lyhyesti

Endpoint
POST /api/v1/ghost-mannequin
Autentikointi
Bearer-API-avain
Käsittely
Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto
1.5–4 min
Credits
4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
Kuvasuhteet
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Syöterajoitukset
Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti
Ei

Pyyntö ja vastaus

Pyyntö

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"
}

Pyyntöparametrit

product_image

Tyyppi: stringPakollinen

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

back_image

Tyyppi: 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

Tyyppi: string

Which side product_image represents.

= front

Arvot: frontback
angle

Tyyppi: 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

Arvot: straightbackside
style

Tyyppi: string

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

= 3d

Arvot: 3dflat_lay
background_color

Tyyppi: string

Background color.

= white

Arvot: whitegraybeigeblack
resolution

Tyyppi: 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

Arvot: 2K4K
aspect_ratio

Tyyppi: string

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

= 3:4

Arvot: 3:41:14:39:1616:9
user_instruction

Tyyppi: 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

Tyyppi: 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.

Virheet

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.

Rajoitukset

  • 600 pyyntöä minuutissa per API-avain (Kiinteä aikaikkuna; rajoitus on sama kaikissa tilauksissa)
  • Vastaus 429 sisältää otsakkeen Retry-After: 30 sekuntia
  • Enintään 10 MB per kuva
  • Formaatit: JPEG, PNG, WebP
  • Rinnakkaiset eräajot per tilaus: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Vain polling — API ei lähetä webhookeja.

Yksi valokuva sisään, yksi näkymätön mallinukke -kuva ulos

Lataa lähdekuva, valitse tyyli, lähetä, pollaa, lataa tulos.

  1. Vaihe 1

    Luo API-avain

    Ghost mannequin käyttää samoja tunnistetietoja kuin kaikki muutkin Photta-ominaisuudet — yksi avain, yksi credits-saldo.

  2. Vaihe 2

    Lataa lähdekuva palveluun

    Välitä julkinen URL tai base64 data URI kentässä `product_image`; lisää `back_image`, kun sinulla on takakuva. JPEG, PNG ja WebP enintään 10 MB per kuva.

  3. Vaihe 3

    Tee POST ghost mannequin -työlle

    Tee POST osoitteeseen `/api/v1/ghost-mannequin` kentillä `product_image`, `style` (`3d` tai `flat_lay`) sekä valinnaisilla kentillä `angle`, `background_color`, `resolution`. Pollaus on ainoa valmistumissignaali — API ei lähetä webhookeja.

  4. Vaihe 4

    Pollaa, kunnes työ valmistuu

    Tee GET `/api/v1/ghost-mannequin/:id` 3 sekunnin välein, kunnes `data.status` on `completed` tai `failed`; tyypillinen valmistumisaika on 1.5–4 minuuttia.

  5. Vaihe 5

    Lataa ja tallenna pysyvästi

    Tuloste on PNG-kuva, josta mallinukke on poistettu ja vaatteen sisäpuoli rekonstruoitu. Ihanteellinen tuotesivujen ghost-kuviin, 3D-vaikutelman tuotegallerioihin ja flat-lay-upotuksiin.

Kysymyksiä, joita kehittäjät kysyvät ennen ghost mannequinin käyttöönottoa

Mitä on ghost mannequin -valokuvaus?

Tuotesivujen käsittelytapa, jossa vaate näyttää leijuvan näkymättömän kehon päällä näyttäen samanaikaisesti muodon ja sisärakenteen. Historiallisesti se yhdistetään useista studiokuvista; Phottan API tuottaa sen yhdellä kutsulla yhdestä mallinukkea käyttävästä valokuvasta.

Paljonko ghost mannequin maksaa?

4 credits tarkkuudella 2K, 5 credits tarkkuudella 4K — yhden creditin halvempi jokaisella tasolla kuin try-on. Epäonnistuneet työt hyvitetään automaattisesti.

Mitä eroa on 3D- ja flat-lay-tyylillä?

`3d`-tyyli säilyttää mallinuken kolmiulotteisen kehonmuodon — vaate säilyttää tilavuutensa, olkapäät ja hihat asettuvat luonnollisesti, ja sisäpuoli rekonstruoidaan. `flat_lay` litistää vaatteen siistiksi 2D-asetteluksi, mikä on ihanteellista kapselikokoelmille tai markkinapaikkailmoituksille, jotka edellyttävät yhdenmukaista suoraan edestä kuvattua muotoa.

Voinko eräkäsitellä useita valokuvia?

Kyllä. Tee POST osoitteeseen `/api/v1/ghost-mannequin/batch` lähdekuvien taulukolla. Vastaus palauttaa erä-ID:n sekä kohteiden generointi-ID:t. Pollaa osoitetta `/api/v1/ghost-mannequin/batch/:id` koontitilalle tai jokaista kohdetta erikseen.

Säilyttääkö se sisäsaumat ja etiketit?

Kyllä — malli rekonstruoi vaatteen sisäpuolen (kaula-aukon sisäpuoli, hihansuiden sisäpuoli, vyötärönauhan vuori) geneerisen pinnan hallusinointien sijaan. Alkuperäisessä kuvassa näkyvät laput ja painetut etiketit säilytetään aina kun mahdollista.

Miten pollaan tulosta?

Tee GET `/api/v1/ghost-mannequin/:id` 3 sekunnin välein. Erätyöt pollaavat päätepistettä, joka palauttaa koontitilan sekä kohdekohtaisen erittelyn.

Liittyvät ominaisuudet

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

Kokeile APIa viidessä minuutissa

Luo Photta-API-avain, liitä yllä oleva cURL-koodinpätkä, ja sinulla on ensimmäinen mallikuva ennen kuin kahvi ehtii tippua.

  • 1.5–4 min
  • 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • asynkroninen, polling
  • 600 pyyntöä/min
  • Bearer-avain