Capability · Ghost mannequin

Ghost mannequin API for hollow-man product photos

In one sentence

Photta's ghost mannequin API takes a garment-on-mannequin photo and returns an invisible-mannequin image with the garment's interior reconstructed. Choose a 3d or flat_lay style, POST, poll every 3 seconds, download when completed.

Get an API key Read the docs

Typical time: 1.5–4 min
Credits: 4 credits at 2K · 5 credits at 4K
Processing: async, polling
Limits: 600 requests/min
Authentication: Bearer key

Every figure on this page comes from the Photta API docs · checked 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 — Example output

At a glance

Endpoint: POST /api/v1/ghost-mannequin
Authentication: Bearer API key
Processing: Asynchronous — poll the status endpoint
Typical time: 1.5–4 min
Credits: 4 credits at 2K · 5 credits at 4K
Aspect ratios: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Input limits: Up to 10 MB per image; JPEG, PNG, WebP
Idempotent: No

Request and response

Request

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

Request parameters

FieldDescription

product_image

Type: stringRequired

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

back_image

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

Type: string

Which side product_image represents.

= front

frontback

angle

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

Type: string

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

= 3d

3dflat_lay

background_color

Type: string

Background color.

= white

whitegraybeigeblack

resolution

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

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

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

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

Errors

StatusTypeMeaning

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.

Limits

600 requests per minute per API key (Fixed window; the limit is the same on every plan)
A 429 carries Retry-After: 30 seconds
Up to 10 MB per image
Formats: JPEG, PNG, WebP
Concurrent batches per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Polling only — the API sends no webhooks.

One photo in, one invisible-mannequin photo out

Upload the source, pick a style, submit, poll, download.

Step 1
Generate an API key
Ghost mannequin uses the same credentials as every other Photta capability — one key, one credit balance.
Step 2
Upload the source photo
Pass a public URL or a base64 data URI in `product_image`; add `back_image` when you have a back view. JPEG, PNG and WebP up to 10 MB per image.
Step 3
POST the ghost mannequin job
POST to `/api/v1/ghost-mannequin` with `product_image`, `style` (`3d` or `flat_lay`) and optional `angle`, `background_color`, `resolution`. Polling is the only completion signal — the API sends no webhooks.
Step 4
Poll until the job completes
GET `/api/v1/ghost-mannequin/:id` every 3 seconds until `data.status` is `completed` or `failed`; typical completion is 1.5 to 4 minutes.
Step 5
Download and persist
The output is a PNG with the mannequin removed and the interior of the garment reconstructed. Ideal for PDP ghost shots, 3D-feel product galleries and flat-lay inserts.

Same endpoint in Node.js, Python and cURL

Questions developers ask before shipping ghost mannequin

What is ghost mannequin photography?

A PDP treatment where the garment appears to float on an invisible body, showing shape and interior construction at once. Historically it's stitched together from multiple studio shots; Photta's API produces it in a single call from one on-mannequin photo.

How much does ghost mannequin cost?

4 credits at 2K, 5 credits at 4K — one credit cheaper at each tier than try-on. Failed jobs refund automatically.

What's the difference between 3D and flat-lay style?

The `3d` style keeps the three-dimensional body shape of the mannequin — the garment retains volume, shoulders and sleeves read naturally, and the interior is reconstructed. `flat_lay` collapses the garment to a clean 2D lay-out, ideal for capsule collections or marketplace listings that expect a consistent front-facing shape.

Can I batch-process multiple photos?

Yes. POST to `/api/v1/ghost-mannequin/batch` with an array of source images. The response gives you a batch ID plus per-item generation IDs. Poll `/api/v1/ghost-mannequin/batch/:id` for an aggregate status or each item individually.

Does it preserve interior seams and labels?

Yes — the model reconstructs the inside of the garment (neckline interior, cuff interior, waistband lining) rather than hallucinating a generic surface. Tags and printed labels visible on the original photo are retained when possible.

How do I poll for the result?

GET `/api/v1/ghost-mannequin/:id` every 3 seconds. Batch jobs poll a parent endpoint that returns an aggregate status plus a per-item breakdown.

Related capabilities

Every figure on this page comes from the Photta API docs · checked 2026-09-10

Try the API in five minutes

Generate a Photta API key, paste the cURL snippet above, and you'll have your first on-model image before the coffee finishes brewing.

Create an account and get an API key Read the docs

1.5–4 min
4 credits at 2K · 5 credits at 4K
async, polling
600 requests/min
Bearer key

Ghost mannequin API for hollow-man product photos

At a glance

Request and response

Request parameters

Errors

One photo in, one invisible-mannequin photo out

Generate an API key

Upload the source photo

POST the ghost mannequin job

Poll until the job completes

Download and persist

Same endpoint in Node.js, Python and cURL

Questions developers ask before shipping ghost mannequin

Related capabilities

Try the API in five minutes