Class: ReveAI::Resources::Images

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

Overview

Note:

By default all images are returned as base64 encoded PNG data; pass accept: "image/png", "image/jpeg", or "image/webp" to any method for raw image bytes instead (see method docs).

Image generation, editing, and remixing operations.

Provides methods for creating images from text prompts, editing existing images, and remixing multiple reference images into new compositions.

Examples:

Generate an image from text

client = ReveAI::Client.new(api_key: "your-key")
result = client.images.create(
  prompt: "A sunset over mountains with a lake in the foreground",
  aspect_ratio: "16:9"
)
puts result.base64 # Base64 encoded PNG

Edit an existing image

result = client.images.edit(
  edit_instruction: "Make the sky more dramatic with storm clouds",
  reference_image: base64_encoded_original
)

Remix multiple images

result = client.images.remix(
  prompt: "Combine the style of <img>0</img> with the subject of <img>1</img>",
  reference_images: [style_image_base64, subject_image_base64]
)

See Also:

Constant Summary collapse

CREATE_ENDPOINT =

Returns API endpoint for image creation.

Returns:

  • (String) —

    API endpoint for image creation

"/v1/image/create"
EDIT_ENDPOINT =

Returns API endpoint for image editing.

Returns:

  • (String) —

    API endpoint for image editing

"/v1/image/edit"
REMIX_ENDPOINT =

Returns API endpoint for image remixing.

Returns:

  • (String) —

    API endpoint for image remixing

"/v1/image/remix"

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

Generates an image from a text prompt.

Examples:

Basic usage

result = client.images.create(prompt: "A cat wearing a top hat")

With aspect ratio

result = client.images.create(
  prompt: "A panoramic mountain landscape",
  aspect_ratio: "16:9"
)

With postprocessing (upscale, then fit within 2048px)

result = client.images.create(
  prompt: "A panoramic mountain landscape",
  postprocessing: [{ process: "upscale", upscale_factor: 2 },
                   { process: "fit_image", max_dim: 2048 }]
)

Request raw WebP bytes instead of JSON

result = client.images.create(prompt: "A sunset", accept: "image/webp")
File.binwrite("sunset.webp", result.image) # raw bytes, no Base64 decode

Save to file

result = client.images.create(prompt: "A sunset")
File.binwrite("image.png", Base64.decode64(result.base64))

Parameters:

  • prompt (String) —

    Text description of the desired image (max 2560 chars)

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

    Output aspect ratio (defaults to API default)

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

    Model version to use (defaults to "latest")

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

    Postprocessing steps applied after generation; each step requires a process key: upscale (+upscale_factor+ 2-4, adds credits cost), remove_background, fit_image (+max_dim+/+max_width+/+max_height+, max 4096, free), effect (+effect_name+, optional effect_parameters overrides nested as { filter_id: { uniform_id: value } })

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

    Effort scaling factor 1-15 (default 1); values above 1 add credits cost, values above 5 only occasionally improve results

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

    Response format: "application/json" (default) or "image/png", "image/jpeg", "image/webp" for raw image bytes, e.g. accept: "image/webp" returns the raw image via result.image (metadata moves to the X-Reve-* response headers)

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

    Request tracking label sent as the breadcrumb query param; ignored by the API, searchable in the Usage page

Options Hash (aspect_ratio:):

  • "16:9" (String) —

    Widescreen landscape

  • "9:16" (String) —

    Portrait (phone)

  • "3:2" (String) —

    Classic landscape

  • "2:3" (String) —

    Classic portrait

  • "4:3" (String) —

    Standard landscape

  • "3:4" (String) —

    Standard portrait

  • "1:1" (String) —

    Square

Returns:

  • (ImageResponse) —

    Response containing base64 encoded image, or raw image bytes when accept is an image format

Raises:

See Also:



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/reve_ai/resources/images.rb', line 111

def create(prompt:, aspect_ratio: nil, version: nil, postprocessing: nil, test_time_scaling: nil,
           accept: nil, breadcrumb: nil)
  validate_prompt!(prompt)
  validate_aspect_ratio!(aspect_ratio)
  validate_postprocessing!(postprocessing)
  validate_test_time_scaling!(test_time_scaling)

  body = { prompt: prompt }
  body[:aspect_ratio] = aspect_ratio if aspect_ratio
  body[:version] = version if version
  body[:postprocessing] = postprocessing if postprocessing
  body[:test_time_scaling] = test_time_scaling if test_time_scaling

  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

#edit(edit_instruction:, reference_image:, aspect_ratio: nil, version: nil, postprocessing: nil, test_time_scaling: nil, accept: nil, breadcrumb: nil) ⇒ ImageResponse

Edits an existing image using text instructions.

Examples:

Change colors

result = client.images.edit(
  edit_instruction: "Change the car color from red to blue",
  reference_image: original_image_base64
)

Add elements

result = client.images.edit(
  edit_instruction: "Add a rainbow in the sky",
  reference_image: landscape_base64
)

Remove the background after editing

result = client.images.edit(
  edit_instruction: "Change the car color from red to blue",
  reference_image: original_image_base64,
  postprocessing: [{ process: "remove_background" }]
)

Parameters:

  • edit_instruction (String) —

    Text description of how to edit the image (max 2560 chars)

  • reference_image (String) —

    Base64 encoded image to edit

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

    Output aspect ratio (defaults to reference image ratio)

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

    Model version to use (defaults to "latest")

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

    Postprocessing steps applied after generation; see #create for the supported step shapes

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

    Effort scaling factor 1-15 (default 1); values above 1 add credits cost

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

    Response format: "application/json" (default) or "image/png", "image/jpeg", "image/webp" for raw image bytes via result.image (metadata moves to the X-Reve-* response headers)

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

    Request tracking label sent as the breadcrumb query param; ignored by the API, searchable in the Usage page

Returns:

  • (ImageResponse) —

    Response containing base64 encoded edited image, or raw image bytes when accept is an image format

Raises:

See Also:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/reve_ai/resources/images.rb', line 178

def edit(edit_instruction:, reference_image:, aspect_ratio: nil, version: nil, postprocessing: nil,
         test_time_scaling: nil, accept: nil, breadcrumb: nil)
  validate_prompt!(edit_instruction, field_name: "Edit instruction")
  validate_reference_image!(reference_image)
  validate_postprocessing!(postprocessing)
  validate_test_time_scaling!(test_time_scaling)

  body = { edit_instruction: edit_instruction, reference_image: reference_image }
  body[:aspect_ratio] = aspect_ratio if aspect_ratio
  body[:version] = version if version
  body[:postprocessing] = postprocessing if postprocessing
  body[:test_time_scaling] = test_time_scaling if test_time_scaling

  params = breadcrumb ? { breadcrumb: breadcrumb } : nil

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

#remix(prompt:, reference_images:, aspect_ratio: nil, version: nil, postprocessing: nil, test_time_scaling: nil, accept: nil, breadcrumb: nil) ⇒ ImageResponse

Creates a new image by remixing multiple reference images.

Use <img>N</img> tags in the prompt to reference specific images, where N is the 0-based index into the reference_images array.

Examples:

Combine two images

result = client.images.remix(
  prompt: "Combine the landscape from <img>0</img> with the sky from <img>1</img>",
  reference_images: [landscape_base64, sky_base64]
)

Style transfer

result = client.images.remix(
  prompt: "Apply the artistic style of <img>0</img> to the photo <img>1</img>",
  reference_images: [artwork_base64, photo_base64]
)

Multiple references

result = client.images.remix(
  prompt: "Create a scene with the dog from <img>0</img>, " \
          "the background from <img>1</img>, and lighting from <img>2</img>",
  reference_images: [dog_base64, background_base64, lighting_ref_base64]
)

Parameters:

  • prompt (String) —

    Text description with optional image references (max 2560 chars)

  • reference_images (Array<String>) —

    Array of base64 encoded images (1-6 images)

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

    Output aspect ratio (defaults to model's choice)

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

    Model version to use (defaults to "latest")

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

    Postprocessing steps applied after generation; see #create for the supported step shapes

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

    Effort scaling factor 1-15 (default 1); values above 1 add credits cost

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

    Response format: "application/json" (default) or "image/png", "image/jpeg", "image/webp" for raw image bytes via result.image (metadata moves to the X-Reve-* response headers)

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

    Request tracking label sent as the breadcrumb query param; ignored by the API, searchable in the Usage page

Returns:

  • (ImageResponse) —

    Response containing base64 encoded remixed image, or raw image bytes when accept is an image format

Raises:

See Also:



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/reve_ai/resources/images.rb', line 247

def remix(prompt:, reference_images:, aspect_ratio: nil, version: nil, postprocessing: nil,
          test_time_scaling: nil, accept: nil, breadcrumb: nil)
  validate_prompt!(prompt)
  validate_reference_images!(reference_images)
  validate_aspect_ratio!(aspect_ratio)
  validate_postprocessing!(postprocessing)
  validate_test_time_scaling!(test_time_scaling)

  body = { prompt: prompt, reference_images: reference_images }
  body[:aspect_ratio] = aspect_ratio if aspect_ratio
  body[:version] = version if version
  body[:postprocessing] = postprocessing if postprocessing
  body[:test_time_scaling] = test_time_scaling if test_time_scaling

  params = breadcrumb ? { breadcrumb: breadcrumb } : nil

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