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

# Room Creation API

> API documentation for the room creation service

# Room Creation API

The Room Creation service allows you to generate realistic interior visualizations from a designated area in an image.

## Generate a room creation

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

This endpoint initiates a new generation to create a room in an area specified by a mask. This operation also creates a new project.

### 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 base image for creation (format: jpg, png)
</ParamField>

<ParamField body="mask_url" type="string" required>
  URL of the mask indicating the area where the room should be generated
</ParamField>

<ParamField body="room_type" type="string" required>
  Type of room to generate. Possible values: "BATHROOM", "KITCHEN", "SHOWEROOM"
</ParamField>

<ParamField body="theme" type="string" required>
  Design theme for the room. Possible values: "MODERN", "INDUSTRIAL", "SCANDINAVIAN", "LUXURIOUS"
</ParamField>

<ParamField body="width" type="number" required>
  Width of the image in pixels
</ParamField>

<ParamField body="height" type="number" required>
  Height of the image in pixels
</ParamField>

<ParamField body="webhook" type="string">
  The URL we call once the generation is complete
</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/create_room/generate' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "user_id": "uuid",
  "image_url": "https://example.com/image.jpg",
  "mask_url": "https://example.com/mask.png",
  "room_type": "KITCHEN",
  "theme": "MODERN",
  "width": 1024,
  "height": 768
}'
```

### Response Example

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

## Generate a room variation

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

This endpoint allows you to generate a variation of a previously created room.

### Request Parameters

<ParamField body="user_id" type="string" required>
  The unique user identifier (UUID)
</ParamField>

<ParamField body="generation_id" type="string" required>
  The unique identifier of the previous generation
</ParamField>

<ParamField body="original_url" type="string" required>
  URL of the original image used for the previous generation
</ParamField>

<ParamField body="mask_url" type="string">
  Optional URL of a new mask. If not provided, the mask from the previous generation will be used
</ParamField>

<ParamField body="room_type" type="string" required>
  Room type for this variation. Possible values: "BATHROOM", "KITCHEN", "SHOWEROOM"
</ParamField>

<ParamField body="theme" type="string" required>
  Design theme for this variation. Possible values: "MODERN", "INDUSTRIAL", "SCANDINAVIAN", "LUXURIOUS"
</ParamField>

<ParamField body="webhook" type="string">
  The URL we call once the generation is complete
</ParamField>

### Response

<ResponseField name="generation_id" type="string">
  The unique identifier of the new generation
</ResponseField>

### Request Example

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

### Response Example

```json theme={null}
{
  "generation_id": "uuid"
}
```

## Retrieve a room creation

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

This endpoint allows you to obtain the result of a previously performed generation.

### Request Parameters

<ParamField body="user_id" type="string" required>
  The unique user identifier (UUID)
</ParamField>

<ParamField body="generation_id" type="string" required>
  The unique identifier of the generation to retrieve
</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/create_room/get' \
--header 'x-api-key: YOUR_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
}
```

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