class RubyLLM::Image

An Image is a generated or edited image. Save it to a file with save or read its bytes with to_blob. Both handle hosted URLs and inline data.

image = RubyLLM.paint("a sunset over mountains in watercolor style")
image.save("sunset.png")

Attributes

data [R]

The Base64-encoded image data, for providers that return the image inline, or nil.

mime_type [R]

The MIME type of the image data, such as "image/png".

model [R]

The id of the model that generated the image.

revised_prompt [R]

The provider’s rewritten version of the prompt, when reported.

url [R]

The URL of the hosted image, for providers that return one, or nil.

Public Class Methods

paint (prompt, model: nil, provider: nil, assume_model_exists: false, size: nil, count: nil, context: nil, with: nil, mask: nil, provider_options: {}, metadata: nil)

Source

# File lib/ruby_llm/image.rb, line 60
def self.paint(prompt,
               model: nil,
               provider: nil,
               assume_model_exists: false,
               size: nil,
               count: nil,
               context: nil,
               with: nil,
               mask: nil,
               provider_options: {},
               metadata: nil)
  config = context&.config || RubyLLM.config
  model ||= config.default_image_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  empty_tokens = Tokens.new
  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.class.display_name,
    model: model.id,
    model_info: model,
    prompt: prompt,
    size: size,
    count: count,
    provider_options: provider_options,
    metadata: metadata,
    tokens: empty_tokens,
    cost: Cost.new(tokens: empty_tokens, model:, category: :images)
  }

  RubyLLM.instrument('image.ruby_llm', payload, config: config) do |event|
    result = provider_instance.paint(prompt, model:, size:, count:, with:, mask:, provider_options:)
    images = Support::Utils.to_safe_array(result)
    event[:result] = result
    event[:response_model] = images.first&.model
    event[:tokens] = Tokens.aggregate(images.map(&:tokens))
    event[:cost] = Cost.aggregate(images.map(&:cost))
    result
  end
end

Generates an image from prompt and returns an Image. Most code calls this through RubyLLM.paint.

model: selects the image model and defaults to the configured default_image_model. provider: forces a specific provider, and assume_model_exists: skips the registry lookup, which is useful for custom endpoints. size: requests dimensions on models that support it. count: asks for several images in one request, returning an Array of Images instead of one. with: passes one or more source images for editing, and mask: constrains which parts of the image may change. provider_options: takes options in the provider’s request vocabulary and merges them into the request as-is. context: supplies a Context whose configuration replaces the global one. metadata: is included in the instrumentation payload.

image = RubyLLM.paint("A small watercolor robot", model: "gpt-image-2")

images = RubyLLM.paint("A small watercolor robot", count: 4)
images.each_with_index { |image, i| image.save("robot-#{i}.png") }

RubyLLM.paint(
  "Turn the logo green and keep the background transparent",
  model: "gpt-image-2",
  with: "logo.png"
)

Providers that cannot generate several images in one request ignore count: and return a single Image.

Public Instance Methods

base64? ()

Source

# File lib/ruby_llm/image.rb, line 122
def base64?
  !@data.nil?
end

Returns true if the image holds inline Base64 data, false otherwise.

cost ()

Source

# File lib/ruby_llm/image.rb, line 171
def cost
  return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?

  Cost.new(tokens:, model: model_info, category: :images, input_details: input_tokens_details)
end

Returns a Cost across every provider attempt, using reported prices when available and registry pricing otherwise.

image.cost.total

model_info ()

Source

# File lib/ruby_llm/image.rb, line 179
def model_info
  return unless model

  @model_info ||= RubyLLM.models.find(model)
rescue ModelNotFoundError
  nil
end

Returns the registry Model for model, or nil if the model id is missing or not in the registry.

save (path)

Source

# File lib/ruby_llm/image.rb, line 145
def save(path)
  File.binwrite(File.expand_path(path), to_blob)
  path
end

Writes the binary image to path, expanding it first. Returns path as given.

image.save("steampunk_owl.png")

to_blob ()

Source

# File lib/ruby_llm/image.rb, line 131
def to_blob
  if base64?
    Base64.decode64 @data
  else
    response = Transport::Connection.basic(config).get @url
    response.body
  end
end

Returns the raw binary image bytes, decoding data when present or downloading from url otherwise.

image_bytes = image.to_blob

tokens ()

Source

# File lib/ruby_llm/image.rb, line 156
def tokens
  return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?

  @tokens ||= Tokens.new(
    input: raw_usage['input_tokens'],
    output: raw_usage['output_tokens'],
    reported_cost: raw_usage['cost']
  )
end

Returns a Tokens with usage across every provider attempt. Its fields are nil when none were reported.

image.tokens.input
image.tokens.output