Skip to main content
There are two popular Ruby libraries for working with OpenAI-compatible APIs: RubyLLM and ruby-openai. Both work seamlessly with Lumenfall.

​
RubyLLM

RubyLLM is the most popular Ruby gem for AI interactions according to GitHub stars. It provides a clean, Ruby-idiomatic interface with a beautiful DSL.

​
Installation

Add to your Gemfile: 
gem "ruby_llm"
Then run: 
bundle install

​
Configuration

require "ruby_llm"

RubyLLM.configure do |config|
  config.openai_api_key = ENV["LUMENFALL_API_KEY"]
  config.openai_api_base = "https://api.lumenfall.ai/openai/v1"
end

​
Generate images

Use the paint method: 
image = RubyLLM.paint(
  "A serene mountain landscape at sunset with dramatic clouds",
  model: "gemini-3-pro-image",
  size: "1024x1024"
)

puts image.url

​
With a client instance

client = RubyLLM::Client.new(
  api_key: ENV["LUMENFALL_API_KEY"],
  api_base: "https://api.lumenfall.ai/openai/v1"
)

image = client.paint(
  "A cyberpunk cityscape at night",
  model: "gpt-image-1.5",
  size: "1792x1024",
  quality: "hd"
)

puts image.url

​
Generate multiple images

images = RubyLLM.paint(
  "Abstract art with vibrant colors",
  model: "gpt-image-1.5",
  n: 4,
  size: "512x512"
)

images.each_with_index do |image, index|
  puts "Image #{index + 1}: #{image.url}"
end

​
Edit images

edited_image = RubyLLM.edit_image(
  image: File.open("original.png"),
  prompt: "Add a rainbow in the sky",
  model: "gpt-image-1.5",
  size: "1024x1024"
)

puts edited_image.url

​
With a mask

edited_image = RubyLLM.edit_image(
  image: File.open("original.png"),
  mask: File.open("mask.png"),
  prompt: "Replace the background with a beach scene",
  model: "gpt-image-1.5",
  size: "1024x1024"
)

​
Rails configuration

Create an initializer at config/initializers/ruby_llm.rb: 
RubyLLM.configure do |config|
  config.openai_api_key = Rails.application.credentials.lumenfall_api_key
  config.openai_api_base = "https://api.lumenfall.ai/openai/v1"
end

​
ruby-openai

ruby-openai is a Ruby client that closely follows the OpenAI API structure.

​
Installation

Add to your Gemfile: 
gem "ruby-openai"
Then run: 
bundle install

​
Configuration

require "openai"

client = OpenAI::Client.new(
  access_token: ENV["LUMENFALL_API_KEY"],
  uri_base: "https://api.lumenfall.ai/openai/v1"
)
Or configure globally: 
OpenAI.configure do |config|
  config.access_token = ENV["LUMENFALL_API_KEY"]
  config.uri_base = "https://api.lumenfall.ai/openai/v1"
end

client = OpenAI::Client.new

​
Generate images

response = client.images.generate(
  parameters: {
    model: "gemini-3-pro-image",
    prompt: "A serene mountain landscape at sunset with dramatic clouds",
    size: "1024x1024",
    n: 1
  }
)

puts response.dig("data", 0, "url")

​
Generation options

response = client.images.generate(
  parameters: {
    model: "gpt-image-1.5",
    prompt: "A beautiful garden with roses",
    size: "1792x1024",      # landscape orientation
    quality: "hd",
    style: "natural",
    response_format: "url",
    n: 1
  }
)

​
Get base64 response

response = client.images.generate(
  parameters: {
    model: "gpt-image-1.5",
    prompt: "A cute robot painting",
    response_format: "b64_json"
  }
)

base64_image = response.dig("data", 0, "b64_json")

​
Edit images

response = client.images.edit(
  parameters: {
    model: "gpt-image-1.5",
    image: File.open("original.png", "rb"),
    prompt: "Add a rainbow in the sky",
    size: "1024x1024",
    n: 1
  }
)

puts response.dig("data", 0, "url")

​
With a mask

response = client.images.edit(
  parameters: {
    model: "gpt-image-1.5",
    image: File.open("original.png", "rb"),
    mask: File.open("mask.png", "rb"),
    prompt: "Replace the background with a beach scene",
    size: "1024x1024"
  }
)

​
List models

models = client.models.list

models["data"].each do |model|
  puts model["id"]
end

​
Rails configuration

Create an initializer at config/initializers/openai.rb: 
OpenAI.configure do |config|
  config.access_token = Rails.application.credentials.lumenfall_api_key
  config.uri_base = "https://api.lumenfall.ai/openai/v1"
end

​
Comparison

FeatureRubyLLMruby-openai
API styleRuby DSLHash-based parameters
Image generationRubyLLM.paintclient.images.generate
Image editingRubyLLM.edit_imageclient.images.edit
ConfigurationGlobal or per-clientPer-client or global
Both libraries are excellent choices. Use RubyLLM if you prefer a more idiomatic Ruby experience, or ruby-openai if you prefer staying close to the OpenAI API structure.

​
Error handling

begin
  image = RubyLLM.paint("A sunset", model: "gemini-3-pro-image")
rescue RubyLLM::AuthenticationError
  puts "Invalid API key"
rescue RubyLLM::RateLimitError
  puts "Rate limit exceeded"
rescue RubyLLM::APIError => e
  puts "API error: #{e.message}"
end

​
Background jobs

Generate images asynchronously with ActiveJob: 
# app/jobs/generate_image_job.rb
class GenerateImageJob < ApplicationJob
  queue_as :default

  def perform(prompt:, model: "gemini-3-pro-image", user_id:)
    image = RubyLLM.paint(prompt, model: model, size: "1024x1024")

    GeneratedImage.create!(
      user_id: user_id,
      prompt: prompt,
      model: model,
      url: image.url
    )
  end
end

# Enqueue the job
GenerateImageJob.perform_later(
  prompt: "A beautiful landscape",
  model: "gemini-3-pro-image",
  user_id: current_user.id
)

​
Next steps

API Reference

Explore the full API documentation.

Available Models

See all available image generation models.