Skip to main content
Besides the offical OpenAI SDK for Ruby, there are two popular community Ruby libraries for working with OpenAI-compatible APIs: RubyLLM and ruby-openai. Both work seamlessly with Lumenfall.

​
RubyLLM

RubyLLM is currently 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

When using RubyLLM with Lumenfall, you must include two parameters in every image generation call (see below for how to include them):
  • provider: "openai" - Tells RubyLLM to always route to Lumenfall’s OpenAI-compatible API
  • assume_model_exists: true - Bypasses RubyLLM’s model registry check to allow models that they don’t officially support
Without these parameters, RubyLLM may attempt to route requests to other providers and the call will fail.

​
Global configuration

Configure the API credentials globally: 
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

​
Per-call configuration

You can also configure RubyLLM per-call without global setup, using RubyLLM.context: 
require "ruby_llm"

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

image = ctx.paint(
  "A capybara relaxing in a hot spring",
  model: "gemini-3-pro-image",
  size: "1024x1024",
  provider: "openai",
  assume_model_exists: true
)

puts image.url
This is useful when you need to make multiple calls with the same configuration or when you need to use different API credentials in different parts of your application.

​
Generate images

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

puts image.url

​
Image editing

RubyLLM does not support image editing. This is a known limitation tracked in GitHub issue #512. To edit images with Lumenfall, use an alternative SDK or make a HTTP call.

​
ruby-openai

ruby-openai is a featureful community-maintained Ruby client that closely follows the OpenAI API structure. It is not the official OpenAI Ruby SDK.

​
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 capybara relaxing in a hot spring",
    size: "1024x1024",
    n: 1
  }
)

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

​
Generate multiple images

response = client.images.generate(
  parameters: {
    model: "gpt-image-1.5",
    prompt: "A capybara relaxing in a hot spring",
    size: "1024x1024",
    n: 2
  }
)

response.dig("data").each_with_index do |image, index|
  puts "Image #{index + 1}: #{image["url"]}"
end

​
Get base64 response

response = client.images.generate(
  parameters: {
    model: "gpt-image-1.5",
    prompt: "A capybara in a forest",
    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 capybara to this image",
    size: "1024x1024",
    n: 1
  }
)

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

​
List models

models = client.models.list

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

​
Retrieve a specific model

model = client.models.retrieve(id: "gemini-3-pro-image")

puts model["id"]
puts model["object"]

​
Next steps

API Reference

Explore the full API documentation.

Available Models

See all available image generation models.