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.

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

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)

{
  "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...",