Class: ReveAI::Resources::V2::Images

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

Overview

Note:

Image generation requests commonly take 40-80 seconds; the API documentation mandates request timeouts of at least 120 seconds (the gem default).

v2 image generation operations.

The v2 create endpoint unifies the v1 create, edit, and remix workflows: a single prompt plus an ordered list of reference images. JSON responses include a structured layout alongside the image.

Examples:

Generate an image from text

result = client.v2.images.create(prompt: "A sunset over mountains")
result.base64 # Base64 encoded PNG
result.layout # => { prompt: "...", regions: [...] }

See Also:

Constant Summary collapse

CREATE_ENDPOINT =

Returns API endpoint for v2 image creation.

Returns:

  • (String) —

    API endpoint for v2 image creation

"/v2/image/create"

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:, references: nil, aspect_ratio: nil, postprocessing: nil, test_time_scaling: nil, version: nil, accept: nil, breadcrumb: nil) ⇒ ImageResponse

Note:

v2 images are significantly larger than v1 images; the API documentation suggests capping the output size with postprocessing: [{ process: "fit_image", max_dim: 2048 }].

Note:

The API documentation does not recommend test_time_scaling for v2 models.

Generates an image from a text prompt with optional reference images.

Reference images are addressed from the prompt with <frame>N</frame> tags, where N is the 0-based index into the references array (so the first reference is <frame>0</frame>).

Examples:

Text-to-image (no references)

result = client.v2.images.create(
  prompt: "A serene mountain landscape at sunset",
  aspect_ratio: "16:9"
)

Edit-style: one reference addressed as 0

result = client.v2.images.create(
  prompt: "Remove the people in the background of <frame>0</frame>.",
  references: [{ data: original_image_base64 }]
)

Remix-style: combine two references

result = client.v2.images.create(
  prompt: "The woman from <frame>0</frame> driving the car from <frame>1</frame>.",
  references: [{ data: woman_base64 }, { data: car_base64 }]
)

Parameters:

  • prompt (String) —

    Text description of the desired image (max 4000 chars); may contain <frame>N</frame> reference tags

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

    Up to 8 reference images (Configuration::V2_MAX_REFERENCES). Each entry is a Hash with exactly one of data (base64 encoded image String) or ref (identifier String: "id:<uuid>" for a previously stored image or generation, "reference:@<name>" for a named reference in your project). Entries are serialized as given.

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

    Output aspect ratio (defaults to the API default of "auto", which lets the model pick); v2 supports the full set in Configuration::ASPECT_RATIOS, including "auto" and "4:1"

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

    Postprocessing steps, each with a process key (e.g., { process: "upscale", upscale_factor: 2 })

  • test_time_scaling (Numeric, nil) (defaults to: nil) —

    Scaling factor (1-15); values above 1 cost more credits

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

    Optional public model version alias, passed through as-is (e.g., "latest", "reve-v2-create@260601")

  • 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 image and, on JSON responses, the generated layout

Raises:

See Also:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/reve_ai/resources/v2/images.rb', line 95

def create(prompt:, references: nil, aspect_ratio: nil, postprocessing: nil,
           test_time_scaling: nil, version: nil, accept: nil, breadcrumb: nil)
  validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH)
  validate_references!(references)
  validate_aspect_ratio!(aspect_ratio, Configuration::ASPECT_RATIOS)
  validate_postprocessing!(postprocessing)
  validate_test_time_scaling!(test_time_scaling)

  body = build_create_body(prompt: prompt, references: references, aspect_ratio: aspect_ratio,
                           postprocessing: postprocessing, test_time_scaling: test_time_scaling,
                           version: version)
  params = breadcrumb ? { breadcrumb: breadcrumb } : nil

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