Return DeferredImage

Author: josefarias

lib/ruby_llm/deferred_image.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents an image that may not yet be fully generated.
+  class DeferredImage
+    include Imageable
+
+    attr_reader :provider_instance, :url
+
+    def initialize(url:, provider_instance:)
+      @url = url
+      @provider_instance = provider_instance
+    end
+
+    def deferred?
+      true
+    end
+
+    def to_blob
+      provider_instance.fetch_image_blob(url)
+    end
+  end
+end

lib/ruby_llm/image.rb

@@ -3,6 +3,8 @@
 module RubyLLM
   # Represents a generated image from an AI model.
   class Image
+    include Imageable
+
     attr_reader :url, :data, :mime_type, :revised_prompt, :model_id
 
     def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil)
@@ -26,11 +28,6 @@ def to_blob
       end
     end
 
-    def save(path)
-      File.binwrite(File.expand_path(path), to_blob)
-      path
-    end
-
     def self.paint(prompt, # rubocop:disable Metrics/ParameterLists
                    model: nil,
                    provider: nil,

lib/ruby_llm/imageable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Mixin for classes that can be used to generate images
+  module Imageable
+    def base64?   = false
+    def deferred? = false
+    def to_blob   = raise NotImplementedError, 'to_blob is not implemented'
+
+    def save(path)
+      if (blob = to_blob)
+        File.binwrite(File.expand_path(path), blob)
+        path
+      end
+    end
+  end
+end

lib/ruby_llm/providers/replicate/images.rb

@@ -30,7 +30,15 @@ def render_image_payload(prompt, model:, **params)
         end
 
         def parse_image_response(response, **)
-          response.body
+          DeferredImage.new(url: response.body.dig('urls', 'get'), provider_instance: self)
+        end
+
+        def fetch_image_blob(url)
+          prediction = @connection.get(url).body
+          return unless prediction['status'] == 'succeeded'
+
+          image_url = Array(prediction['output']).first
+          @connection.get(image_url).body
         end
 
         private

spec/fixtures/vcr_cassettes/image_basic_functionality_google_imagen-4-ultra_an_official_replicate_model_can_paint_images.yml

@@ -22,6 +22,10 @@ def save_and_verify_image(image)
   end
 end
 
+def wait_for_deferred_image
+  sleep(15) if VCR.current_cassette.recording?
+end
+
 RSpec.describe RubyLLM::Image do
   include_context 'with configured RubyLLM'
 
@@ -60,27 +64,34 @@ def save_and_verify_image(image)
     end
 
     it 'google/imagen-4-ultra, an official replicate model, can paint images' do
-      response = RubyLLM.paint('a siamese cat', model: 'google/imagen-4-ultra')
+      image = RubyLLM.paint('a siamese cat', model: 'google/imagen-4-ultra', output_format: 'png')
 
-      expect(response).to be_a(Hash)
-      expect(response.dig('urls', 'get')).to be_present
+      expect(image.deferred?).to be(true)
+
+      wait_for_deferred_image
+      save_and_verify_image image
     end
 
     it 'google/nano-banana, an official replicate model, can paint images with custom parameters' do
       ref_img1 = 'https://replicate.delivery/pbxt/NbYIclp4A5HWLsJ8lF5KgiYSNaLBBT1jUcYcHYQmN1uy5OnN/tmpcqc07f_q.png'
       ref_img2 = 'https://replicate.delivery/pbxt/NbYId45yH8s04sptdtPcGqFIhV7zS5GTcdS3TtNliyTAoYPO/Screenshot%202025-08-26%20at%205.30.12%E2%80%AFPM.png'
-      response = RubyLLM.paint('a siamese cat', model: 'google/nano-banana',
-                                                image_input: [ref_img1, ref_img2])
+      image = RubyLLM.paint('a siamese cat', model: 'google/nano-banana',
+                                             image_input: [ref_img1, ref_img2],
+                                             output_format: 'png')
 
-      expect(response).to be_a(Hash)
-      expect(response.dig('urls', 'get')).to be_present
+      expect(image.deferred?).to be(true)
+
+      wait_for_deferred_image
+      save_and_verify_image image
     end
 
     it 'prunaai/hidream-l1-fast, an unofficial replicate model, can paint images' do
-      response = RubyLLM.paint('a siamese cat', model: 'prunaai/hidream-l1-fast')
+      image = RubyLLM.paint('a siamese cat', model: 'prunaai/hidream-l1-fast', output_format: 'png')
 
-      expect(response).to be_a(Hash)
-      expect(response.dig('urls', 'get')).to be_present
+      expect(image.deferred?).to be(true)
+
+      wait_for_deferred_image
+      save_and_verify_image image
     end
 
     it 'validates model existence' do

spec/fixtures/vcr_cassettes/image_basic_functionality_google_nano-banana_an_official_replicate_model_can_paint_images_with_custom_parameters.yml

@@ -13,7 +13,7 @@
 
   config.around do |example|
     cassette_name = example.full_description.parameterize(separator: '_').delete_prefix('rubyllm_')
-    VCR.use_cassette(cassette_name, record: :new_episodes) do
+    VCR.use_cassette(cassette_name) do
       example.run
     end
   end