Reve API - Docs - v2/create_layout

Create Layout

Create or edit a structured layout from a prompt, ordered mixed references, and optional commands. This endpoint is experimental and best suited for agents and custom tooling. For image generation, consider using the create endpoint instead. To learn more about pricing, visit the pricing page.

Working with references

This endpoint takes ordered compound references. Each entry may contain an image, a layout, a descriptive prompt, or any combination of those fields. Use image-only references for visual freedom and include layouts when structure must be preserved.

Compound references

The layout endpoints (create_layout and render_layout) take compound references — objects that pair an image with a layout — rather than raw image objects. Each entry provides an optional image, an optional layout, and an optional prompt.

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

The image follows the same shape as any image input (exactly one of data or ref), and the layout follows the layout schema described.

Request Headers

• Authorization: The API Key provided as a bearer token.

Request Body

• prompt: The desired layout description (max 4000 characters). At least one of prompt or references is required.
• references: Up to eight ordered compound references containing optional fields.
• commands: Optional layout edits.
• aspect_ratio: Desired aspect ratio (e.g., 4:1, 3:1, etc.). Default: auto.
• version: Optional public model version alias.

JSON Response Body

Successful responses (200)

• layout: The layout produced by the model. See the Layouts section for the format.
• content_violation: Indicates if a content policy violation occurred.
• request_id: A unique id for the request.
• credits_used: Credits used for this request.
• credits_remaining: Credits remaining in your budget.

Layouts

A layout describes the content and composition of an image. It includes:

• Prompt: Overall caption of the image.
• Width/Height: Pixel dimensions of the layout.
• Regions: An array describing each rectangular area within the image.

Regions

Each region has:

• label: Unique entity name (region id).
• prompt: Description.
• bbox: Coordinates in normalized 0.0–1.0.
• color_palette: Optional RGB colors.
• parent: Label of a containing region, if applicable.
• region_type: Level of detail or special-handling hint (e.g., coarse_detail, medium_detail, fine_detail).

Example JSON Response

{
  "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 with centered black serif text...",
        "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...",
    "width": 4672,
    "height": 3520
  },
  "content_violation": false,
  "request_id": "rsid-...",
  "credits_used": 80,
  "credits_remaining": 880
}