Last updated February 09, 2026

The Stability AI Stable Image Ultra (stability-image-ultra) model allows you to generate high-quality, detailed images from descriptive text prompts. This guide walks you through how to access the v1-images-generations API using Ruby.

Prerequisites

1. Attach an inference addon to an app of yours:

   # If you don't have an app yet, you can create one with:
   heroku create $APP_NAME # specify the name you want for your app (or skip this step to use an existing app you have)
   
   # Create and attach one of our chat models to your app, $APP_NAME:
   heroku addons:create heroku-inference:standard -a $APP_NAME --as INFERENCE
   

Ruby Example Code

# frozen_string_literal: true

require 'net/http'
require 'json'
require 'uri'
require 'base64'

DIFFUSION_URL = ENV.fetch('DIFFUSION_URL') do
  raise <<~ERROR
    Environment variable 'DIFFUSION_URL' is missing.
    Set it using:
      export DIFFUSION_URL=$(heroku config:get -a $APP_NAME DIFFUSION_URL)
  ERROR
end

DIFFUSION_KEY = ENV.fetch('DIFFUSION_KEY') do
  raise <<~ERROR
    Environment variable 'DIFFUSION_KEY' is missing.
    Set it using:
      export DIFFUSION_KEY=$(heroku config:get -a $APP_NAME DIFFUSION_KEY)
  ERROR
end

##
# Opens an image file using the default image viewer based on the operating system.
#
# @param filename [String] The name of the file to open.
def open_image_file(filename)
  case RUBY_PLATFORM
  when /darwin/  then system('open', filename)      # macOS
  when /linux/   then system('xdg-open', filename)  # Linux
  when /mingw|mswin/
    system('start', filename)                       # Windows
  else
    puts 'Automatic image opening is not supported on this platform.'
  end
end

##
# Parses and processes the API response for the image generation request.
#
# @param response   [Net::HTTPResponse] The response from the API.
# @param payload    [Hash] The original request payload.
# @param open_image [Boolean] Flag to automatically open the image after creation.
# @param filename   [String, nil] Filename to save. If not provided, a default is generated.
def parse_image_output(response, payload, open_image: false, filename: nil)
  if response.is_a?(Net::HTTPSuccess)
    result = JSON.parse(response.body)

    if payload[:response_format] == 'base64'
      # Generate a default filename if none is provided, based on the prompt
      filename ||= payload[:prompt][0..19].gsub(' ', '_').downcase + '.png'
      File.open(filename, 'wb') do |file|
        file.write(Base64.decode64(result.dig('data', 0, 'b64_json')))
      end

      puts "Image saved as #{filename}"
      open_image_file(filename) if open_image
    else
      puts "Download the image from: #{result.dig('data', 0, 'url')}"
    end
  else
    puts "Request failed: #{response.code}, #{response.body}"
  end
end

##
# Generates an image using the Stability AI Stable Image Ultra model and saves it to a file.
#
# @param payload    [Hash] The parameters for the image generation.
# @param open_image [Boolean] Flag to open the image automatically after generation.
# @param filename   [String, nil] Name of the saved file. Defaults to a truncated version of the prompt.
def generate_image(payload, open_image: false, filename: nil)
  uri = URI.join(DIFFUSION_URL, '/v1/images/generations')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{DIFFUSION_KEY}"
  request['Content-Type']  = 'application/json'
  request.body             = payload.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  parse_image_output(response, payload, open_image: open_image, filename: filename)
end

# Example payload
payload = {
  model:          'stable-image-ultra',
  prompt:          'A surreal landscape with glowing mushrooms under a night sky.',
  aspect_ratio:    '16:9',
  output_format:   'png',
  seed:            123,
  negative_prompt: 'crowded, noisy, chaotic',
  response_format: 'base64'  # Add this key if you want the base64 variant
}

# Generate the image with the given payload
generate_image(payload, open_image: true)