Capability · Ghost mannequin

API Ghost mannequin per foto prodotto con manichino invisibile

In sintesi

L'API ghost mannequin di Photta riceve la foto di un capo indossato da un manichino e restituisce un'immagine con manichino invisibile e interno del capo ricostruito. Scegli uno stile 3d o flat_lay, invia via POST, esegui il polling ogni 3 secondi, scarica al completamento.

Ottieni una chiave API Leggi la documentazione

Tempo tipico: 1.5–4 min
Credits: 4 credits a 2K · 5 credits a 4K
Elaborazione: asincrono, polling
Limiti: 600 richieste/min
Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato 2026-09-10

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')

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.status

import 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"]

A garment shown without its mannequin by the ghost mannequin API — Esempio di output

Panoramica

Endpoint: POST /api/v1/ghost-mannequin
Autenticazione: API key Bearer
Elaborazione: Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico: 1.5–4 min
Credits: 4 credits a 2K · 5 credits a 4K
Rapporti d'aspetto: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input: Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente: No

Richiesta e risposta

Richiesta

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.status

import 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 / Completato

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

Parametri della richiesta

CampoDescrizione

product_image

Tipo: stringObbligatorio

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

back_image

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

Tipo: string

Which side product_image represents.

= front

frontback

angle

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

straightbackside

style

Tipo: string

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

= 3d

3dflat_lay

background_color

Tipo: string

Background color.

= white

whitegraybeigeblack

resolution

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

2K4K

aspect_ratio

Tipo: string

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

= 3:4

3:41:14:39:1616:9

user_instruction

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

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

Errori

StatoTipoSignificato

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.

Limiti

600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
Un 429 restituisce Retry-After: 30 secondi
Fino a 10 MB per immagine
Formati: JPEG, PNG, WebP
Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Solo polling — l'API non invia webhook.

Una foto in ingresso, una foto con manichino invisibile in uscita

Carica l'origine, scegli uno stile, invia, fai polling, scarica.

Passaggio 1
Genera una chiave API
Ghost mannequin usa le stesse credenziali di ogni altra funzionalità di Photta — una chiave, un unico saldo di credits.
Passaggio 2
Carica la foto sorgente
Passa un URL pubblico o un URI dati base64 in `product_image`; aggiungi `back_image` quando hai una vista posteriore. JPEG, PNG e WebP fino a 10 MB per immagine.
Passaggio 3
Invia il job ghost mannequin con POST
Invia una richiesta POST a `/api/v1/ghost-mannequin` con `product_image`, `style` (`3d` o `flat_lay`) e i campi opzionali `angle`, `background_color`, `resolution`. Il polling è l'unico segnale di completamento — l'API non invia webhook.
Passaggio 4
Esegui il polling fino al completamento del job
Esegui una GET su `/api/v1/ghost-mannequin/:id` ogni 3 secondi finché `data.status` non è `completed` o `failed`; il completamento richiede tipicamente da 1.5 a 4 minuti.
Passaggio 5
Scarica e mantieni
L'output è un PNG con il manichino rimosso e l'interno del capo ricostruito. Ideale per scatti ghost per PDP, gallerie prodotto con effetto 3D e inserti flat-lay.

Stesso endpoint in Node.js, Python e cURL

Domande che gli sviluppatori si pongono prima di rilasciare ghost mannequin

Cos'è la fotografia ghost mannequin?

Un trattamento per PDP in cui il capo sembra fluttuare su un corpo invisibile, mostrando contemporaneamente la forma e la struttura interna. Storicamente viene composto unendo più scatti in studio; l'API di Photta lo produce in una singola chiamata da un'unica foto su manichino.

Quanto costa ghost mannequin?

4 credits a 2K, 5 credits a 4K — un credito in meno per ciascun livello rispetto al try-on. I job non riusciti vengono rimborsati automaticamente.

Qual è la differenza tra lo stile 3D e quello flat-lay?

Lo stile `3d` mantiene la forma tridimensionale del corpo del manichino: il capo conserva volume, spalle e maniche risultano naturali e l'interno viene ricostruito. Lo stile `flat_lay` appiattisce il capo in una stesura 2D pulita, ideale per collezioni capsule o inserzioni su marketplace che richiedono una forma frontale uniforme.

Posso elaborare più foto in batch?

Sì. Invia una POST a `/api/v1/ghost-mannequin/batch` con un array di immagini sorgente. La risposta restituisce un ID batch insieme agli ID di generazione per singolo elemento. Esegui il polling su `/api/v1/ghost-mannequin/batch/:id` per uno stato aggregato o per ciascun elemento singolarmente.

Mantiene le cuciture interne e le etichette?

Sì — il modello ricostruisce l'interno del capo (interno del colletto, interno dei polsini, fodera della cintura) invece di allucinare una superficie generica. I cartellini e le etichette stampate visibili nella foto originale vengono mantenuti, ove possibile.

Come eseguo il polling per il risultato?

Esegui una GET su `/api/v1/ghost-mannequin/:id` ogni 3 secondi. I job in batch eseguono il polling su un endpoint padre che restituisce uno stato aggregato insieme al dettaglio per singolo elemento.

Funzionalità correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato 2026-09-10

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

Crea un account e ottieni una chiave API Leggi la documentazione

1.5–4 min
4 credits a 2K · 5 credits a 4K
asincrono, polling
600 richieste/min
Chiave Bearer

API Ghost mannequin per foto prodotto con manichino invisibile

Panoramica

Richiesta e risposta

Parametri della richiesta

Errori

Una foto in ingresso, una foto con manichino invisibile in uscita

Genera una chiave API

Carica la foto sorgente

Invia il job ghost mannequin con POST

Esegui il polling fino al completamento del job

Scarica e mantieni

Stesso endpoint in Node.js, Python e cURL

Domande che gli sviluppatori si pongono prima di rilasciare ghost mannequin

Funzionalità correlate

Prova l'API in 5 minuti