Add Replicate provider

Current replicate models output images

Drop 'replicate' prefix from model names

Force array on replicate webhook filters

Run models rake tasks

I hacked the models refresh logic to append the replicate models to existing ones.
Without this patch, the whole file would get overwritten and models would be missing,
seeing as I don’t have credentials for all supported providers.

Fold image size into model params

Record model list cassettes

Add tests

Return DeferredImage

Poll in deferred image tests

Imageable -> Blobbable

Remove unnecessary test

No need to set `@model_id`

Update docs

Typo

Author: josefarias

bin/console

@@ -23,6 +23,8 @@ RubyLLM.configure do |config|
   config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
   config.openrouter_api_key = ENV.fetch('OPENROUTER_API_KEY', nil)
   config.perplexity_api_key = ENV.fetch('PERPLEXITY_API_KEY', nil)
+  config.replicate_api_key = ENV.fetch('REPLICATE_API_KEY', nil)
+  config.replicate_webhook_url = ENV.fetch('REPLICATE_WEBHOOK_URL', nil)
   config.vertexai_location = ENV.fetch('GOOGLE_CLOUD_LOCATION', nil)
   config.vertexai_project_id = ENV.fetch('GOOGLE_CLOUD_PROJECT', nil)
 end

docs/_core_features/image-generation.md

@@ -26,6 +26,7 @@ After reading this guide, you will know:
 *   How to generate images from text prompts.
 *   How to select different image generation models.
 *   How to specify image sizes (for supported models).
+*   How to use model hosting platforms like Replicate.
 *   How to access and save generated image data (URL or Base64).
 *   How to integrate image generation with Rails Active Storage.
 *   Tips for writing effective image prompts.
@@ -119,12 +120,32 @@ image_portrait = RubyLLM.paint(
 )
 ```
 
-> Not all models support size customization. If a size is specified for a model that doesn't support it (like Google Imagen), RubyLLM may log a debug message indicating the size parameter is ignored. Check the provider's documentation or the [Available Models Guide]({% link _reference/available-models.md %}) for supported sizes.
+> Not all models support size customization. Check the provider's documentation or the [Available Models Guide]({% link _reference/available-models.md %}) for supported sizes.
+{: .note }
+
+## Using model hosting platforms
+
+Platforms like Replicate host a large collection of models with different capabilities and parameters. Due to the variety of models available, you should be aware of the parameters supported by the model you're using. This information is available in the platform's documentation.
+
+For example, Imagen 4 Ultra supports `aspect_ratio` as a parameter when used [via Replicate](https://replicate.com/google/imagen-4-ultra). Since it's optional, you can omit it. But if you'd like to specify a value, you just need to add it to your paint call.
+
+```ruby
+image = RubyLLM.paint(
+  "A photorealistic image of a red panda coding Ruby on a laptop",
+  model: "google/imagen-4-ultra",
+  provider: :replicate,
+  aspect_ratio: "16:9"
+)
+```
+
+> When switching between different models, you'll typically need to change the parameters as well, since different models support different parameter sets. Always check the model's documentation for the specific parameters it accepts.
 {: .note }
 
 ## Working with Generated Images
 
-The `RubyLLM::Image` object provides access to the generated image data and metadata.
+When models return the image immediately, the `RubyLLM::Image` object provides access to the generated image data and metadata.
+
+Some models generate images asynchronously. In this case, you will receive a `RubyLLM::DeferredImage` object instead. You can still access the image data, but you will either need to wait for the image to be generated or fetch it by other means—typically after being notified via a webhook.
 
 ### Accessing Image Data
 
@@ -133,6 +154,10 @@ The `RubyLLM::Image` object provides access to the generated image data and meta
 *   `image.mime_type`: Returns the MIME type (e.g., `"image/png"`, `"image/jpeg"`).
 *   `image.base64?`: Returns `true` if the image data is Base64-encoded, `false` otherwise.
 
+### Accessing Deferred Image Data
+
+*   `deferred_image.url`: Returns the URL where you can check whether the image has been generated.
+
 ### Saving Images Locally
 
 The `save` method works regardless of whether the image was delivered via URL or Base64. It fetches the data if necessary and writes it to the specified file path.
@@ -150,9 +175,23 @@ rescue => e
 end
 ```
 
+For deferred images, the `save` method will write the file and return its path only if the image has been generated. Otherwise, it will return `nil`.
+
+The ideal way to handle deferred images is by having the provider notify you via webhook when the image is generated, and then fetching the image outside of RubyLLM. But if you're not able to configure a webhook, another way to handle these is to call the method recursively with a delay until it succeeds or a condition is met. This is equivalent to a "polling" mechanism. Check your provider's documentation for any rate limits that may apply.
+
+```ruby
+# Only do this if you're not able to configure a webhook
+def save_deferred_image(image, path, remaining_attempts = 10)
+  return nil if remaining_attempts <= 0
+  image.save(path) || (sleep(2) && save_deferred_image(image, path, remaining_attempts - 1))
+end
+
+save_deferred_image(deferred_image, "deferred_image.png")
+```
+
 ### Getting Raw Image Blob
 
-The `to_blob` method returns the raw binary image data (decoded from Base64 or downloaded from URL). This is useful for integration with other libraries or frameworks.
+The `to_blob` method returns the raw binary image data (decoded from Base64 or downloaded from URL). This is useful for integration with other libraries or frameworks. Deferred images return `nil` if the image has not finished generating.
 
 ```ruby
 image = RubyLLM.paint("Abstract geometric patterns in pastel colors")
@@ -277,4 +316,4 @@ Image generation can take several seconds (typically 5-20 seconds depending on t
 
 *   [Chatting with AI Models]({% link _core_features/chat.md %}): Learn about conversational AI.
 *   [Embeddings]({% link _core_features/embeddings.md %}): Explore text vector representations.
-*   [Error Handling]({% link _advanced/error-handling.md %}): Master handling API errors.
+*   [Error Handling]({% link _advanced/error-handling.md %}): Master handling API errors.

docs/_getting_started/configuration.md

@@ -59,6 +59,8 @@ RubyLLM.configure do |config|
   config.mistral_api_key = ENV['MISTRAL_API_KEY']
   config.perplexity_api_key = ENV['PERPLEXITY_API_KEY']
   config.openrouter_api_key = ENV['OPENROUTER_API_KEY']
+  config.replicate_api_key = ENV['REPLICATE_API_KEY']
+  config.replicate_webhook_url = ENV['REPLICATE_WEBHOOK_URL']
 
   # Local providers
   config.ollama_api_base = 'http://localhost:11434/v1'
@@ -363,4 +365,4 @@ Now that you've configured RubyLLM, you're ready to:
 
 - [Start chatting with AI models]({% link _core_features/chat.md %})
 - [Work with different providers and models]({% link _advanced/models.md %})
-- [Set up Rails integration]({% link _advanced/rails.md %})
+- [Set up Rails integration]({% link _advanced/rails.md %})