### Extract Layout

# Extract a structured layout from an image, optionally guided by a prompt. Returns JSON only. Layout generation requests commonly take 10–40 seconds to complete. Configure HTTP clients, load balancers, and job runners with request timeouts of at least 120 seconds.

This is an experimental endpoint that requires care and experimentation to achieve good results. It is best suited for agents and custom tooling. For simple image generation and prompt-based image editing, use the create endpoint instead. To learn more about the pricing for this endpoint, visit the [pricing page](https://api.reve.com/console/pricing).

## Request Headers

Authorization: string required

The API Key provided as a bearer token.

## Request Body

- `image`: object required 
  The source image, provided with exactly one of `data` or `ref`.
- `prompt`: string 
  An optional instruction for transforming the extracted layout.
- `version`: string 
  An optional public model version alias.

### JSON Request

#### cURL Example
```curl
REVE_API_KEY=""

curl -X POST https://api.reve.com/v2/image/extract_layout \ 
  -H "Authorization: Bearer $REVE_API_KEY" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "image": { "data": "'"$(base64 < image.jpg | tr -d '\n')"'" },
    "version": "latest"
  }'
```

### Layouts

A layout (the `layout` field) is a structured JSON object describing the content and composition of an image. It has an optional `prompt`, an optional `normalized_edit_instruction`, optional `width/height`, and a `regions` array.

#### Regions
Each region describes a rectangular area within the image:
- `label`: A short, unique entity name (the region id).
- `prompt`: What appears in that region.
- `bbox`: `x0`, `y0` (top-left) and `x1`, `y1` (bottom-right) in normalized 0.0–1.0 coordinates.
- `color_palette`: Optional RGB colors for appearance. Each entry is an object with `r`, `g`, and `b`.
- `parent`: The label of a containing region.
- `region_type`: A hint for detail level.

### Overview

Every image input — a raw reference image, or the base image for `extract_layout` — is supplied as an object with exactly one of two fields:
- `data`: the raw image bytes, base64-encoded.
- `ref`: a string that points to an image already stored in your project.

### Successful JSON Response (200)

```json
{
  "layout": {
    "regions": [
      {
        "label": "<bottle 1>",
        "prompt": "Tall, slender glass bottle filled with a salmon-pink rosé wine...",
        "bbox": {
          "x0": 0.371,
          "x1": 0.511,
          "y0": 0.07,
          "y1": 0.869
        },
        "color_palette": [
          { "r": 242, "g": 115, "b": 83 },
          { "r": 249, "g": 172, "b": 159 }
        ],
        "region_type": "coarse_detail"
      },
      {
        "label": "<label 1>",
        "prompt": "Off-white rectangular paper label...",
        "bbox": {
          "x0": 0.379,
          "x1": 0.507,
          "y0": 0.562,
          "y1": 0.756
        },
        "parent": "<bottle 1>",
        "region_type": "fine_detail"
      }
    ],
    "prompt": "A professional product photo shows a bottle of rosé wine...",