Class: ReveAI::Resources::V2::Layouts

Inherits:
Base
  • Object
show all
Defined in:
lib/reve_ai/resources/v2/layouts.rb

Overview

Note:

Experimental: these endpoints require care and experimentation to achieve good results. For simple image generation and prompt-based editing, prefer Images#create.

v2 layout pipeline operations (experimental).

The layout endpoints expose lower-level control over image composition: extracting structured layouts from images, generating layouts from prompts, and rendering images from layouts.

See Also:

Constant Summary collapse

EXTRACT_ENDPOINT =

Returns API endpoint for layout extraction.

Returns:

  • (String) —

    API endpoint for layout extraction

"/v2/image/extract_layout"
CREATE_ENDPOINT =

Returns API endpoint for layout generation.

Returns:

  • (String) —

    API endpoint for layout generation

"/v2/image/create_layout"
RENDER_ENDPOINT =

Returns API endpoint for layout rendering.

Returns:

  • (String) —

    API endpoint for layout rendering

"/v2/image/render_layout"

Instance Attribute Summary

Attributes inherited from Base

#client

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from ReveAI::Resources::Base

Instance Method Details

#create(prompt: nil, references: nil, commands: nil, aspect_ratio: nil, version: nil, breadcrumb: nil) ⇒ LayoutResponse

Note:

Experimental: layout generation commonly takes 10-40 seconds.

Generates (or edits) a structured layout without rendering an image.

Examples:

Free-form layout from a prompt

result = client.v2.layouts.create(prompt: "a person at a cafe")
result.layout[:regions] # => [{ label: "person", bbox: {...}, ... }]

Parameters:

  • prompt (String, nil) (defaults to: nil) —

    Description of the desired layout (max 4000 chars); at least one of prompt or references is required

  • references (Array<Hash>, nil) (defaults to: nil) —

    Up to 8 ordered compound references (Configuration::V2_MAX_REFERENCES); each entry may contain image (a raw { data: }/{ ref: } image Hash), layout (a layout Hash), and/or prompt (String) — at least one per entry

  • commands (Array<Hash>, nil) (defaults to: nil) —

    Ordered imperative layout edits; each entry is a Hash with an op key (add, place, shift, remove, keep, change) plus op-specific fields

  • aspect_ratio (String, nil) (defaults to: nil) —

    Layout aspect ratio; supported set (Configuration::ASPECT_RATIOS), default "auto"

  • version (String, nil) (defaults to: nil) —

    Optional public model version alias

  • breadcrumb (String, nil) (defaults to: nil) —

    Request tracking value sent as the breadcrumb query parameter; ignored by the API

Returns:

Raises:

  • (ValidationError) —

    if neither prompt nor references is given, or any argument is malformed



88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/reve_ai/resources/v2/layouts.rb', line 88

def create(prompt: nil, references: nil, commands: nil, aspect_ratio: nil, version: nil, breadcrumb: nil)
  validate_prompt_or_references!(prompt, references)
  validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH) if prompt
  validate_compound_references!(references)
  validate_commands!(commands)
  validate_aspect_ratio!(aspect_ratio, Configuration::ASPECT_RATIOS)

  body = build_create_body(prompt: prompt, references: references, commands: commands,
                           aspect_ratio: aspect_ratio, version: version)

  response = post(CREATE_ENDPOINT, body, params: breadcrumb_params(breadcrumb))
  LayoutResponse.new(status: response.status, headers: response.headers, body: response.body)
end

#extract(image:, prompt: nil, version: nil, breadcrumb: nil) ⇒ LayoutResponse

Note:

Experimental: layout extraction commonly takes 10-40 seconds.

Extracts a structured layout from an image.

Examples:

Extract a layout from an image

result = client.v2.layouts.extract(image: { data: photo_base64 })
result.layout # => { prompt: "...", regions: [...], width: 4672, height: 3520 }

Parameters:

  • image (Hash) —

    Source image: exactly one of data (base64 encoded image String) or ref (identifier String: "id:<uuid>" or "reference:@<name>")

  • prompt (String, nil) (defaults to: nil) —

    Optional instruction for transforming the extracted layout (max 4000 chars)

  • version (String, nil) (defaults to: nil) —

    Optional public model version alias

  • breadcrumb (String, nil) (defaults to: nil) —

    Request tracking value sent as the breadcrumb query parameter; ignored by the API

Returns:

Raises:



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/reve_ai/resources/v2/layouts.rb', line 49

def extract(image:, prompt: nil, version: nil, breadcrumb: nil)
  validate_raw_image!(image, "Image")
  validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH) if prompt

  body = { image: image }
  body[:prompt] = prompt if prompt
  body[:version] = version if version

  response = post(EXTRACT_ENDPOINT, body, params: breadcrumb_params(breadcrumb))
  LayoutResponse.new(status: response.status, headers: response.headers, body: response.body)
end

#render(layout:, references: nil, postprocessing: nil, version: nil, accept: nil, breadcrumb: nil) ⇒ ImageResponse

Note:

Experimental: rendering commonly takes 40-80 seconds.

Renders a final image from a target layout.

Examples:

Render a layout to an image

layout = { regions: [{ label: "cat", prompt: "a tabby cat",
                       bbox: { x0: 0.2, y0: 0.2, x1: 0.8, y1: 0.8 } }] }
result = client.v2.layouts.render(layout: layout)
File.binwrite("cat.png", Base64.decode64(result.image))

Parameters:

  • layout (Hash) —

    The layout to render; must include a non-empty regions Array (each region: label, prompt, bbox with normalized x0/y0/x1/y1; optional parent, region_type, image_index, image_region_index)

  • references (Array<Hash>, nil) (defaults to: nil) —

    Up to 8 ordered compound references; same shape as #create

  • postprocessing (Array<Hash>, nil) (defaults to: nil) —

    Postprocessing steps, each with a process key (e.g., { process: "fit_image", max_dim: 2048 })

  • version (String, nil) (defaults to: nil) —

    Optional public model version alias

  • accept (String, nil) (defaults to: nil) —

    Per-request Accept header: "image/png", "image/jpeg", or "image/webp" for a binary image response, or "application/json" (default)

  • breadcrumb (String, nil) (defaults to: nil) —

    Request tracking value sent as the breadcrumb query parameter; ignored by the API

Returns:

  • (ImageResponse) —

    Response containing the rendered image and the produced layout

Raises:



131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/reve_ai/resources/v2/layouts.rb', line 131

def render(layout:, references: nil, postprocessing: nil, version: nil, accept: nil, breadcrumb: nil)
  validate_layout!(layout)
  validate_compound_references!(references)
  validate_postprocessing!(postprocessing)

  body = { layout: layout }
  body[:references] = references if references
  body[:postprocessing] = postprocessing if postprocessing
  body[:version] = version if version

  response = post(RENDER_ENDPOINT, body, params: breadcrumb_params(breadcrumb), accept: accept)
  ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
end