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
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "gm_d4e5f6",
"status": "completed",
"style": "3d",
"angle": "side",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/gm_d4e5f6.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_d4e5f6-thumb.jpg",
"credits_used": 4,
"created_at": "2026-04-10T16:00:00Z",
"completed_at": "2026-04-10T16:00:48Z",
"duration_ms": 48000
},
"request_id": "req_gm002"
}Pyyntöparametrit
product_imageTyyppi: stringPakollinen
URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).
back_imageTyyppi: 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_sideTyyppi: string
Which side product_image represents.
= front
Arvot:frontbackangleTyyppi: 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:straightbacksidestyleTyyppi: string
Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).
= 3d
Arvot:3dflat_laybackground_colorTyyppi: string
Background color.
= white
Arvot:whitegraybeigeblackresolutionTyyppi: 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:2K4Kaspect_ratioTyyppi: 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:9user_instructionTyyppi: 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_idTyyppi: 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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
Vaihe 1
Luo API-avain
Ghost mannequin käyttää samoja tunnistetietoja kuin kaikki muutkin Photta-ominaisuudet — yksi avain, yksi credits-saldo.
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.
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.
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.
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.
Sama endpoint ympäristöissä Node.js, Python ja cURL
Node.js
Ghost mannequin API ympäristössä Node.js
Kutsu Phottan ominaisuutta ghost mannequin API Node.js-taustajärjestelmästä natiivilla fetchillä. SDK:ta ei tarvita: tallenna avaimesi, lähetä työ, pollaa tulosta.
LuePython
Ghost mannequin API Pythonissa
Kutsu Phottan ghost mannequin API -ominaisuutta Pythonissa requests-kirjaston avulla. Kolmenkymmenen rivin kääre, async-yhteensopiva httpx:n kautta, toimii Djangossa, FastAPIssa ja Celeryssä.
LuecURL
Ghost mannequin API cURLillä
Kutsu Phottan ghost mannequin API-rajapintaa suoraan komentoriviltä cURLin avulla. Lähetä, pollaa, lataa — jokainen koodinpätkä toimii yhdessä jq:n kanssa skriptatuissa putkissa.
Lue
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
Ominaisuudet
Virtuaalinen try-on API vaatteille
REST API, joka asettaa vaatteet tekoälymallinukkejen päälle. Asynkroninen, 1.5–4 minuutin generointi, 5 credits resoluutiolla 2K, 6 resoluutiolla 4K. cURL-, Node.js- ja Python-esimerkit.
Katso endpointOminaisuudet
Korujen try-on-API kaulakoruille, sormuksille, rannekoruille ja korvakoruille
Sovita kaulakoruja, sormuksia, rannekoruja ja korvakoruja AI-malleille RESTin kautta. 5 credits resoluutiolla 2K, sisäänrakennetut lähikuvamallit, heijastukset huomioiva renderöinti Photta-dokumentaation mukaisesti.
Katso endpointRakenna
Automatisoi ghost mannequin -irrotus katalogillesi
Resepti öiseen katalogiautomaatioon: hae eilisen tuotepäivitykset, lähetä eränä Phottan ghost-mannequin-rajapintaan, pollaa pääerää, tallenna tietokantaasi.
Katso endpointVertailu
Photta vs Pixazo — suora putki vai malliaggregaattori
Photta vs Pixazo vertailussa: oma muotipipeline vastaan usean mallin aggregaattori. Endpointit, viive, ilmaisversio ja kompromissit. Lähdetiedot 2026-04-19.
Katso endpointPikaopas
Ensimmäinen Photta-kuva alle viidessä minuutissa.
Rekisteröidy, luo API-avain, suorita ensimmäinen cURL-kutsusi, tee pollingia valmistumiseen asti ja tallenna tulos. Viisi vaihetta, dokumentoitu alusta loppuun.
Katso endpointReferenssi
Photta API -virheet
Täydellinen luettelo Photta API -virhetyypeistä statuskoodeineen, virheen rungon rakenne ja tiedot siitä, mitkä virheet kannattaa yrittää uudelleen.
Katso endpointReferenssi
Photta API:n rate limitit
Photta API:n rate limit, sen aikaikkuna, Retry-After-otsake, pollausväli ja tilauskohtaiset rinnakkaisuusrajat, kaikki API-dokumentaatiosta luettuna.
Katso endpoint
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