Layouts

With Reve's layout model, an image is a structure you can edit: every visual element is addressable in code. This page describes the layout object shared by the layout endpoints.

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:

• 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 that condition the appearance of the region. Each entry is an object with r, g, and b integer channels in the inclusive range 0–255. The service normalizes these values for the rendering model. Keep the layout's prompts consistent with the palette: prompts must not contradict the conditioned colors, and conditioning works best when the region prompt also names the intended color (for example, a red car with { "r": 255, "g": 0, "b": 0 }).
• parent: The label of a containing region, for hierarchical layouts. Omit for top-level regions.
• region_type: A level-of-detail / special-handling hint.
  • coarse_detail: a high-level object, such as a person or a car.
  • medium_detail: a medium object, such as an arm, a belt, or a wheel, whose parent is a coarse_detail region.
  • fine_detail: a fine detail, such as a ring, a buckle, or a lug nut, whose parent is a medium_detail region.
  • text: a region of text embedded into the image.
  • hand: a special region kind for human hands.
  • face: a special region kind for human faces.
• image_index and image_region_index: Optional cross-image references into the supplied reference images.

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. Use this to send an image directly with the request.
• ref: a string that points to an image already stored in your project, in one of the two forms below.

Reference strings

• id:: the literal prefix id: followed by the UUID of an object in your project. The UUID may name an individual image, or a generation (in which case the generation's output image is used). You can find the UUID of a specific object by inspecting it with your browser's developer tools while viewing the project.
• reference:@: the literal prefix reference:@ followed by the name of a named reference in your project. The first image attached to that reference is used.

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.

Layout endpoints

• Extract Layout: Extract a layout from an existing image.
• Create Layout: Generate a layout from a prompt and optional reference images.
• Render Layout: Render a layout into a final image.