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

# Decluttering API

> API documentation for the image decluttering service

# Decluttering API

The decluttering service allows you to automatically remove unwanted objects from your interior photos, creating cleaner and more attractive spaces for your real estate listings.

## Generate a decluttered image

<ParamField path="POST /api/declutter_total/generate" />

Calling this endpoint launches a new generation to declutter an image. This endpoint also creates a new project; depending on your subscription, it is possible to obtain free variations on the same project.

As generation can take several minutes, the result is not immediately available. You can either provide a webhook URL or regularly query the retrieval API.

### Request Parameters

<ParamField body="user_id" type="string" required>
  The unique user identifier (UUID) that you can retrieve from your Developer Space
</ParamField>

<ParamField body="image_url" type="string" required>
  URL of the image you want to declutter (format: jpg, png)
</ParamField>

<ParamField body="auto" type="boolean">
  If set to true, the AI will automatically detect objects to remove. Otherwise, you will need to provide a mask.
</ParamField>

<ParamField body="webhook" type="string">
  The URL we call once the generation is complete. The request body is the same as the response from the retrieval API
</ParamField>

### Response

<ResponseField name="generation_id" type="string">
  The unique generation identifier (UUID) to use with the retrieval API
</ResponseField>

<ResponseField name="remaining_photos" type="number">
  The number of photos remaining after this generation
</ResponseField>

<ResponseField name="project_id" type="string">
  The unique project identifier (UUID)
</ResponseField>

### Request Example

```bash theme={null}
curl --request POST \
--url 'https://iacrea.com/api/declutter_total/generate' \
--header x-api-key:API_KEY \
--header 'Content-Type: application/json' \
--data '{
  "user_id": "uuid",
  "image_url": "https://my-image-url.jpg",
  "auto": true
}'
```

### Response Example

```json theme={null}
{
  "generation_id": "uuid",
  "remaining_photos": 100,
  "project_id": "uuid"
}
```

## Generate a variation of a decluttered image

<ParamField path="POST /api/declutter_total/generate-variation" />

Calling this endpoint allows you to generate a variation of a previously decluttered image, optionally specifying a new mask. As generation can take several minutes, the result is not immediately available.

### Request Parameters

<ParamField body="user_id" type="string" required>
  The unique user identifier (UUID) that you can retrieve from your Developer Space
</ParamField>

<ParamField body="generation_id" type="string" required>
  The unique identifier of the previous generation you want to create a variation of
</ParamField>

<ParamField body="original_url" type="string" required>
  URL of the original image to declutter
</ParamField>

<ParamField body="mask_url" type="string" required>
  URL of the mask indicating areas to declutter
</ParamField>

### Response

<ResponseField name="generation_id" type="string">
  The unique identifier of the new generation (UUID) to use with the retrieval API
</ResponseField>

<ResponseField name="remaining_photos" type="number">
  The number of photos remaining after this generation
</ResponseField>

### Request Example

```bash theme={null}
curl --request POST \
--url 'https://iacrea.com/api/declutter_total/generate-variation' \
--header x-api-key:API_KEY \
--header 'Content-Type: application/json' \
--data '{
  "user_id": "uuid",
  "generation_id": "uuid",
  "original_url": "https://my-image-url.jpg",
  "mask_url": "https://my-mask-url.png"
}'
```

### Response Example

```json theme={null}
{
  "generation_id": "uuid",
  "remaining_photos": 100
}
```

## Retrieve a decluttered image

<ParamField path="POST /api/declutter_total/get" />

This endpoint allows you to obtain the result of a previously performed generation. It lets you know the status of your generation and retrieve the URL of your generated images.

**Important note:** In case of "FAILED" status, your photos are automatically refunded.

### Request Parameters

<ParamField body="user_id" type="string" required>
  The unique user identifier (UUID) that you can retrieve from your Developer Space
</ParamField>

<ParamField body="generation_id" type="string" required>
  The unique generation identifier (UUID) returned by the generation API
</ParamField>

### Response

<ResponseField name="status" type="string">
  The generation status: "STARTING", "PROCESSING", "SUCCEEDED", "FAILED"
</ResponseField>

<ResponseField name="urls" type="array">
  An array containing the URLs of generated images (present only if status="SUCCEEDED")
</ResponseField>

<ResponseField name="variationNumber" type="number">
  The number of variations already performed on this project
</ResponseField>

### Request Example

```bash theme={null}
curl --request POST \
--url 'https://iacrea.com/api/declutter_total/get' \
--header x-api-key:API_KEY \
--header 'Content-Type: application/json' \
--data '{
  "user_id": "uuid",
  "generation_id": "uuid"
}'
```

### Response Example

```json theme={null}
{
  "status": "SUCCEEDED",
  "urls": ["https://generated-image-url"],
  "variationNumber": 2
}
```