Reve API - Docs - v2/render_layout

Render Layout

Render an image from a target layout and optional ordered mixed references. Image generation requests commonly take 40–80 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.

POST https://api.reve.com/v2/image/render_layout

Result

Request Headers

Authorization string required

The API Key provided as a bearer token.

Accept string

One of image/png, image/jpeg, image/webp or application/json. For images, the response will be the bytes directly in the requested format, with the additional information provided as custom headers. For JSON, the response will be an object with the image base64 encoded (png) with additional information provided as separate properties.

Default: application/json

Compound references

The layout endpoints (create_layout and render_layout) take compound references — objects that pair an image with a layout — rather than the raw image objects used by v2/image/create. Each entry provides any of an optional image, an optional layout, and an optional prompt, so the model can relate pixels to structured regions.

{
  "image": { "data": "<base64>" },  // or { "ref": "id:<uuid>" }; optional
  "layout": { "prompt": "...", "regions": [ ... ] },  // optional
  "prompt": "..."  // optional
}

Request Body

layout object required

The target layout to render.

references array

Up to eight ordered mixed image, layout, and descriptive-prompt references.

postprocessing array

Optional postprocessing operations applied to the rendered image.

version string

An optional public model version alias.

JSON Request

curl -X POST https://api.reve.com/v2/image/render_layout \
  -H "Authorization: Bearer $REVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "layout": {
    "regions": [\
      {\
        "label": "<bottle 1>",\
        "prompt": "Tall, slender glass bottle filled with a salmon-pink rosé wine. The bottle has a metallic rose-gold foil capsule covering the neck and cork. A clean white rectangular label on the lower body features black serif text: <text>YVES</text> in a small font, above a large <text>ROSÉ</text>, and a bottom line of smaller text <text>Côtes de Provence - 2024</text>. The glass reflects vertical highlights from an external light source. The base of the bottle is thick and clear, showing the pink liquid pooling at the bottom.",\
        "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": "<brick 1>",\
        "prompt": "Rustic background wall composed of large, rectangular terracotta bricks in earthy shades of reddish-brown and burnt orange. A thick, uneven horizontal stone ledge runs across the top, catching bright sunlight on its image-left side. Below the ledge, the bricks are arranged in a staggered pattern with deep, dark recessed mortar lines. The brick surfaces are matte and slightly weathered, with some showing darker, charred-looking patches.",\
        "bbox": {\
          "x0": 0,\
          "x1": 1,\
          "y0": 0,\
          "y1": 0.557\
        },\
        "region_type": "medium_detail"\
      }\
    ],\
    "prompt": "A professional product photo shows a bottle of rosé wine and two glasses on a terracotta-tiled surface, bathed in warm, direct sunlight. The scene has a rustic, Mediterranean aesthetic with a color palette of warm oranges, terracotta, soft pinks, and creamy whites.\n\nIn the center of the frame, a tall, slender <bottle 1> of rosé wine stands upright. The glass is clear, revealing the salmon-pink liquid inside. The <bottle 1> has a rose-gold metallic foil capsule covering its neck. A white rectangular label on the front of the <bottle 1> features black serif text that reads <text>YVES</text> in a small font, <text>ROSÉ</text> in a large, bold font, and <text>Côtes de Provence - 2024</text> in a smaller font at the bottom.\n\nTo the image-left of the <bottle 1>, an empty, stemless wine <glass 1> sits on the tiles. To the image-right of the <bottle 1>, a second stemless wine <glass 2> is partially filled with the same salmon-pink rosé wine. In the foreground, just in front of and to the right of the <bottle 1>, a small sprig of green <rosemary 1> lies horizontally on the tiles.\n\nBehind the <bottle 1> and the <glass 2>, a light beige, textured linen <cloth 1> is draped haphazardly, with its folds catching the sunlight. The entire arrangement sits on a surface of square terracotta <tile 1> pieces with visible grout lines.\n\nThe background consists of a rustic wall made of large, irregular terracotta <brick 1> blocks. The lighting comes from the upper left, casting long, soft shadows to the right and creating bright highlights on the glass and metallic surfaces. In the far upper-right corner, a dark, out-of-focus vertical <object 1>, possibly a kitchen faucet or part of a fixture, is partially visible.",
    "width": 4672,
    "height": 3520
  },
  "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 (the overall caption of the image), an optional normalized_edit_instruction (emitted by create_layout, and accepted by render_layout), optional width/height (the pixel dimensions of the layout's coordinate frame, emitted by the layout endpoints — always multiples of 32 — and used by render_layout to honor the layout's aspect ratio; when supplied on input, provide both, each a multiple of 32, with width * height between 30722560 and 40964096), and a regions array.

Regions

Each region describes a rectangular area within the image:

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:

Reference strings

References are intended mainly for reusing standard assets across many requests — scene backgrounds, logotypes, recurring characters, and the like — without re-sending the bytes every time.

Reference shape depends on the endpoint family: v2/image/create takes raw image objects directly in references. The layout pipeline endpoints take compound reference objects with an image and optional layout instead, so the model can relate pixels to structured regions.

JSON Response Body

For successful responses (200)

image string

The base64-encoded rendered image.

layout object

The layout produced by the model. See the Layouts section for the format.

content_violation boolean

Whether the request tripped a content policy violation. When true, layout is omitted.

request_id string

A unique id for the request.

credits_used number

Credits used for this request.

credits_remaining number

Credits remaining in your budget.