> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt
> Use this file to discover all available pages before exploring further.

# Ghost Mannequin API

> Remove mannequins from product photos via the image API.

Use `POST /api/v1/images/ghost-mannequin` to remove a visible mannequin from a product photo and return a hosted generated image URL.

## Authentication

Send an OmniCommerce API key with the `catalog:enrich` scope:

```http theme={null}
Authorization: Bearer $OMNI_API_KEY
Content-Type: application/json
```

## Request

```http theme={null}
POST /api/v1/images/ghost-mannequin
```

```json theme={null}
{
  "imageUrl": "https://cdn.example.com/products/dress-front.jpg",
  "productTitle": "Linen Wrap Dress",
  "categoryName": "Women Clothes > Dresses"
}
```

`imageUrl` must be a public HTTP(S) URL. Data URIs are rejected so image payloads are not embedded in API calls.
`productTitle`, `categoryName`, and `categoryId` are optional context fields. When provided, they are passed to the image-edit prompt only to help preserve the correct garment or product type.

## Generation Settings

The endpoint uses the same working generation settings as the product UI flow:

```json theme={null}
{
  "prompt": "Remove mannequin plus optional product title/category context",
  "aspect_ratio": "match_input_image",
  "go_fast": true,
  "output_format": "webp",
  "output_quality": 80
}
```

Each successful generation is recorded in the organization AI usage ledger as `image_generation` with feature `ghost_mannequin_image_edit`.

## Response

```json theme={null}
{
  "ok": true,
  "apiVersion": "developer_v1",
  "operationId": "8f7e8f8f-2b9e-46e6-a2c0-50d0f4612b2d",
  "status": "completed",
  "warnings": [],
  "recommendations": [],
  "image": "https://cdn.example.com/generated/ghost-mannequin.webp"
}
```

The `image` value is the generated remote HTTP(S) URL stored by OmniCommerce.

## Errors

* `400` - invalid JSON, missing `imageUrl`, non-HTTP URL, or data URI input.
* `401` - missing or invalid API key.
* `403` - API key does not have `catalog:enrich`.
* `502` - image generation failed or the generated result could not be downloaded.