generate_image 1.1.2.2 → 2.0.0

data/generate_image.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/generate_image/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "generate_image"
+  spec.version = GenerateImage::VERSION
+  spec.authors = ["AMQOR Merouane"]
+  spec.email = ["marouaneamqor@gmail.com"]
+
+  spec.summary = "OpenAI Images API client (GPT Image, DALL·E) for Ruby"
+  spec.description = <<~DESC
+    Lightweight Ruby client for OpenAI image generation and edits (/v1/images/generations, /v1/images/edits).
+    Defaults to GPT Image models; stdlib-only (Net::HTTP + JSON). Ruby 3.1+.
+  DESC
+  spec.homepage = "https://github.com/merouaneamqor/generate_image"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  rescue StandardError
+    Dir["lib/**/*", "LICENSE.txt", "README.md", "CHANGELOG.md"]
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webmock", "~> 3.19"
+end

data/lib/generate_image/client.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module GenerateImage
+  class Client
+    DEPRECATE_GENERATE_IMAGE_MSG =
+      "[DEPRECATION] GenerateImage::Client#generate_image is deprecated; use #generate instead."
+
+    def initialize(api_key = nil)
+      @api_key_override = api_key
+    end
+
+    def generate(prompt, **opts)
+      raise ValidationError, "prompt must be a non-empty String" unless prompt.is_a?(String) && !prompt.strip.empty?
+
+      model = (opts[:model] || configuration.default_model).to_s
+      validate_generation_model!(model)
+
+      body = build_generation_body(prompt, model, opts)
+      parsed = http.post_json("/v1/images/generations", body)
+      Response.new(parsed, model: model)
+    end
+
+    def edit(image:, prompt:, **opts)
+      raise ValidationError, "prompt must be a non-empty String" unless prompt.is_a?(String) && !prompt.strip.empty?
+      raise ValidationError, "image is required" if image.nil?
+
+      model = (opts[:model] || configuration.default_model).to_s
+      validate_edit_model!(model)
+
+      fields = build_edit_fields(model, prompt, opts)
+      files = { "image" => image }
+      files["mask"] = opts[:mask] if opts[:mask]
+
+      parsed = http.post_multipart("/v1/images/edits", fields, files)
+      Response.new(parsed, model: model)
+    end
+
+    def generate_image(text, options = {})
+      warn "#{DEPRECATE_GENERATE_IMAGE_MSG}\n"
+      generate(text, **legacy_options_to_new(options)).to_h
+    end
+
+    private
+
+    def configuration
+      base = GenerateImage.configuration
+      if @api_key_override && !@api_key_override.to_s.strip.empty?
+        KeyOverride.new(base, @api_key_override)
+      else
+        base
+      end
+    end
+
+    def http
+      @http ||= HTTP.new(configuration: configuration)
+    end
+
+    def build_generation_body(prompt, model, opts)
+      cfg = configuration
+      n = (opts.key?(:n) ? opts[:n] : 1).to_i
+      size = (opts[:size] || cfg.default_size).to_s
+
+      validate_generation_n!(model, n)
+      validate_generation_size!(model, size)
+
+      body = {
+        prompt: prompt,
+        model: model,
+        n: n,
+        size: size
+      }
+
+      if Models.gpt_image?(model)
+        body[:quality] = (opts[:quality] || cfg.default_quality).to_s
+        of = opts[:output_format] || cfg.default_output_format
+        body[:output_format] = of.to_s if of && !of.to_s.empty?
+        body[:background] = opts[:background].to_s if opts[:background]
+        body[:response_format] = opts[:response_format].to_s if opts[:response_format]
+        body[:style] = opts[:style].to_s if opts[:style]
+      elsif Models.dall_e_3?(model)
+        body[:quality] = (opts[:quality] || "standard").to_s
+        body[:response_format] = (opts[:response_format] || "url").to_s
+        body[:style] = opts[:style].to_s if opts[:style]
+      else
+        body[:response_format] = opts[:response_format].to_s if opts[:response_format]
+      end
+
+      body[:user] = opts[:user].to_s if opts[:user]
+      body.compact
+    end
+
+    def build_edit_fields(model, prompt, opts)
+      cfg = configuration
+      n = (opts.key?(:n) ? opts[:n] : 1).to_i
+      size = (opts[:size] || cfg.default_size).to_s
+
+      validate_generation_n!(model, n)
+      validate_generation_size!(model, size)
+
+      fields = {
+        "model" => model,
+        "prompt" => prompt,
+        "n" => n.to_s,
+        "size" => size
+      }
+
+      if Models.gpt_image?(model)
+        fields["quality"] = (opts[:quality] || cfg.default_quality).to_s
+        of = opts[:output_format] || cfg.default_output_format
+        fields["output_format"] = of.to_s if of && !of.to_s.empty?
+        fields["background"] = opts[:background].to_s if opts[:background]
+        fields["input_fidelity"] = opts[:input_fidelity].to_s if opts[:input_fidelity]
+        fields["response_format"] = opts[:response_format].to_s if opts[:response_format]
+      elsif Models.dall_e_3?(model)
+        fields["quality"] = (opts[:quality] || "standard").to_s
+        fields["response_format"] = (opts[:response_format] || "url").to_s
+      elsif opts[:response_format]
+        fields["response_format"] = opts[:response_format].to_s
+      end
+
+      fields["user"] = opts[:user].to_s if opts[:user]
+      fields.compact
+    end
+
+    def validate_generation_model!(model)
+      return if Models::ALL.include?(model)
+
+      raise ValidationError, "Unknown model #{model.inspect}. Expected one of: #{Models::ALL.join(", ")}"
+    end
+
+    def validate_edit_model!(model)
+      # Edits are supported for gpt-image and dall-e-2 historically; dall-e-3 may differ — allow gpt + dall-e-2 + dall-e-3 per API
+      return if Models.gpt_image?(model) || model == Models::DALLE2 || model == Models::DALLE3
+
+      raise ValidationError,
+            "Unsupported edit model #{model.inspect}. Use a GPT Image model, #{Models::DALLE2}, or #{Models::DALLE3}."
+    end
+
+    def validate_generation_n!(model, n)
+      raise ValidationError, "n must be between 1 and 10" unless n >= 1 && n <= 10
+
+      return unless Models.dall_e_3?(model)
+
+      raise ValidationError, "n must be 1 for #{model}" if n != 1
+    end
+
+    def validate_generation_size!(model, size)
+      valid =
+        if Models.gpt_image?(model)
+          Models::GPT_IMAGE_SIZES.include?(size)
+        elsif Models.dall_e_3?(model)
+          Models::DALLE3_SIZES.include?(size)
+        else
+          Models::DALLE2_SIZES.include?(size)
+        end
+
+      return if valid
+
+      allowed =
+        if Models.gpt_image?(model)
+          Models::GPT_IMAGE_SIZES
+        elsif Models.dall_e_3?(model)
+          Models::DALLE3_SIZES
+        else
+          Models::DALLE2_SIZES
+        end
+
+      raise ValidationError, "Invalid size #{size.inspect} for #{model}. Allowed: #{allowed.join(", ")}"
+    end
+
+    def legacy_options_to_new(options)
+      h = options.transform_keys { |k| k.to_sym }
+      if h.key?(:num_images)
+        h[:n] = h.delete(:num_images)
+      end
+      if h.key?(:response_format)
+        case h[:response_format].to_s
+        when "base64", "b64"
+          h[:response_format] = "b64_json"
+        end
+      end
+      h
+    end
+
+    class KeyOverride < SimpleDelegator
+      def initialize(base, api_key)
+        super(base)
+        @override_key = api_key
+      end
+
+      def resolved_api_key
+        s = @override_key.to_s
+        return s unless s.strip.empty?
+
+        __getobj__.resolved_api_key
+      end
+    end
+  end
+end

data/lib/generate_image/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GenerateImage
+  class Configuration
+    attr_accessor :api_key, :default_model, :base_url, :default_size, :default_quality,
+                  :default_output_format, :open_timeout, :read_timeout, :max_retries
+
+    def initialize
+      @api_key = nil
+      @default_model = "gpt-image-1"
+      @base_url = "https://api.openai.com"
+      @default_size = "1024x1024"
+      @default_quality = "auto"
+      @default_output_format = "png"
+      @open_timeout = 30
+      @read_timeout = 120
+      @max_retries = 1
+    end
+
+    def resolved_api_key
+      [api_key, ENV["OPENAI_API_KEY"], ENV["DALL_E_API_KEY"]]
+        .compact
+        .map(&:to_s)
+        .find { |s| !s.strip.empty? }
+    end
+  end
+end

data/lib/generate_image/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GenerateImage
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: 1)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status_code, :body
+
+    def initialize(message = nil, status_code: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+  end
+
+  class ValidationError < Error; end
+
+  # @deprecated Use {ApiError} instead. Kept for v1.x rescue compatibility.
+  RequestFailed = ApiError
+end

data/lib/generate_image/http.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "stringio"
+require "uri"
+
+module GenerateImage
+  class HTTP
+    def initialize(configuration:)
+      @configuration = configuration
+    end
+
+    def post_json(path, body_hash)
+      uri = build_uri(path)
+      body = JSON.generate(body_hash)
+
+      with_retries do
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = body
+        perform(uri, request)
+      end
+    end
+
+    def post_multipart(path, fields, files)
+      uri = build_uri(path)
+      boundary = "----RubyGenerateImage#{SecureRandom.hex(16)}"
+      body = build_multipart_body(boundary, fields, files)
+
+      with_retries do
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{api_key}"
+        request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        request.body = body
+        perform(uri, request)
+      end
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def api_key
+      key = configuration.resolved_api_key
+      raise AuthenticationError, "Missing API key. Set OPENAI_API_KEY or configure api_key." if key.nil? || key.strip.empty?
+
+      key
+    end
+
+    def build_uri(path)
+      base = configuration.base_url.to_s.chomp("/")
+      URI.join("#{base}/", path.delete_prefix("/"))
+    end
+
+    def perform(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = configuration.open_timeout
+      http.read_timeout = configuration.read_timeout
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200, 201
+        parse_json_body(response.body)
+      when 401
+        raise AuthenticationError, error_message_from(response)
+      when 429
+        raise RateLimitError.new(
+          error_message_from(response),
+          retry_after: parse_retry_after(response["Retry-After"])
+        )
+      else
+        raise ApiError.new(error_message_from(response), status_code: response.code.to_i, body: response.body)
+      end
+    end
+
+    def parse_json_body(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise ApiError.new("Invalid JSON response", body: body)
+    end
+
+    def error_message_from(response)
+      parsed = safe_parse_json(response.body)
+      err = parsed["error"]
+      if err.is_a?(Hash)
+        err["message"] || err.inspect
+      elsif err.is_a?(String)
+        err
+      else
+        "HTTP #{response.code}: #{response.message}"
+      end
+    rescue StandardError
+      "HTTP #{response.code}: #{response.message}"
+    end
+
+    def safe_parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError, TypeError
+      {}
+    end
+
+    def parse_retry_after(value)
+      s = value.to_s.strip
+      return 1 if s.empty?
+
+      if s.match?(/^\d+$/)
+        s.to_i.clamp(1, 120)
+      else
+        1
+      end
+    end
+
+    def with_retries
+      attempts = 0
+      max = [configuration.max_retries.to_i, 0].max
+
+      begin
+        yield
+      rescue RateLimitError => e
+        attempts += 1
+        raise e if attempts > max
+
+        sleep(e.retry_after.to_f.positive? ? e.retry_after : 1)
+        retry
+      end
+    end
+
+    def build_multipart_body(boundary, fields, files)
+      io = StringIO.new
+      crlf = "\r\n"
+
+      fields.each do |name, value|
+        next if value.nil?
+
+        io << "--#{boundary}#{crlf}"
+        io << "Content-Disposition: form-data; name=\"#{escape_name(name)}\"#{crlf}#{crlf}"
+        io << value.to_s
+        io << crlf
+      end
+
+      files.each do |name, file_spec|
+        filename, content, content_type = normalize_file_spec(name, file_spec)
+        io << "--#{boundary}#{crlf}"
+        io << "Content-Disposition: form-data; name=\"#{escape_name(name)}\"; filename=\"#{escape_filename(filename)}\"#{crlf}"
+        io << "Content-Type: #{content_type}#{crlf}#{crlf}"
+        io << content
+        io << crlf
+      end
+
+      io << "--#{boundary}--#{crlf}"
+      io.string
+    end
+
+    def escape_name(name)
+      name.to_s.gsub(/["\r\n]/, "")
+    end
+
+    def escape_filename(name)
+      name.to_s.gsub(/["\r\n]/, "")
+    end
+
+    def normalize_file_spec(name, spec)
+      case spec
+      when String
+        path = spec
+        [File.basename(path), File.binread(path), mime_for_path(path)]
+      when Pathname
+        path = spec.to_s
+        [File.basename(path), File.binread(path), mime_for_path(path)]
+      when Hash
+        filename = spec[:filename] || spec["filename"] || "image.png"
+        io = spec[:io] || spec["io"]
+        content_type = spec[:content_type] || spec["content_type"] || "application/octet-stream"
+        content =
+          if io.respond_to?(:read)
+            io.rewind if io.respond_to?(:rewind)
+            io.read
+          else
+            spec[:data] || spec["data"] || ""
+          end
+        [filename, content, content_type]
+      else
+        if spec.respond_to?(:read)
+          filename = spec.respond_to?(:path) && spec.path ? File.basename(spec.path) : "#{name}.png"
+          spec.rewind if spec.respond_to?(:rewind)
+          [filename, spec.read, "application/octet-stream"]
+        else
+          raise ValidationError, "Unsupported file payload for #{name}"
+        end
+      end
+    end
+
+    def mime_for_path(path)
+      case File.extname(path).downcase
+      when ".png" then "image/png"
+      when ".jpg", ".jpeg" then "image/jpeg"
+      when ".webp" then "image/webp"
+      when ".gif" then "image/gif"
+      else "application/octet-stream"
+      end
+    end
+  end
+end

data/lib/generate_image/models.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GenerateImage
+  module Models
+    GPT_IMAGE = %w[gpt-image-1 gpt-image-1.5 gpt-image-1-mini].freeze
+    DALLE3 = "dall-e-3"
+    DALLE2 = "dall-e-2"
+
+    ALL = (GPT_IMAGE + [DALLE3, DALLE2]).freeze
+
+    GPT_IMAGE_SIZES = %w[auto 1024x1024 1536x1024 1024x1536].freeze
+    DALLE3_SIZES = %w[1024x1024 1792x1024 1024x1792].freeze
+    DALLE2_SIZES = %w[256x256 512x512 1024x1024].freeze
+
+    GPT_IMAGE_QUALITIES = %w[auto high medium low].freeze
+    DALLE3_QUALITIES = %w[standard hd].freeze
+
+    OUTPUT_FORMATS = %w[png jpeg webp].freeze
+
+    module_function
+
+    def gpt_image?(model)
+      GPT_IMAGE.include?(model.to_s)
+    end
+
+    def dall_e_3?(model)
+      model.to_s == DALLE3
+    end
+  end
+end

data/lib/generate_image/response.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GenerateImage
+  class Response
+    attr_reader :raw, :model
+
+    def initialize(parsed_json, model: nil)
+      @raw = parsed_json
+      @model = model
+    end
+
+    def data_items
+      Array(raw["data"])
+    end
+
+    def images
+      data_items.map do |item|
+        if item["url"]
+          { url: item["url"] }
+        elsif item["b64_json"]
+          { b64_json: item["b64_json"] }
+        else
+          {}
+        end
+      end
+    end
+
+    def url
+      data_items.find { |d| d["url"] }&.fetch("url", nil)
+    end
+
+    def b64
+      data_items.find { |d| d["b64_json"] }&.fetch("b64_json", nil)
+    end
+
+    def usage
+      raw["usage"]
+    end
+
+    def created
+      raw["created"]
+    end
+
+    def to_h
+      if url
+        { image_url: url }
+      elsif b64
+        { image_base64: b64 }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/generate_image/version.rb

@@ -1,3 +1,5 @@
-module GenerateImage
-  VERSION = "1.1.2.2"
-end
+# frozen_string_literal: true
+
+module GenerateImage
+  VERSION = "2.0.0"
+end

data/lib/generate_image.rb

@@ -1,46 +1,21 @@
-require 'net/http'
-require 'json'
-
-module GenerateImage
-  class RequestFailed < StandardError; end
-
-  class Client
-    API_ENDPOINT = 'https://api.openai.com/v1/images/generations'
-
-    def initialize(api_key = nil)
-      @api_key = api_key || ENV['DALL_E_API_KEY']
-    end
-
-    def generate_image(text, options = {})
-      unless @api_key
-        raise StandardError, "API Key not set"
-      end
-      uri = URI(API_ENDPOINT)
-      request = Net::HTTP::Post.new(uri)
-      request['Content-Type'] = 'application/json'
-      request['Authorization'] = "Bearer #{API_KEY}"
-      request.body = {
-        prompt: text,
-        n: options[:num_images] || 1,
-        size: options[:size] || '512x512',
-        response_format: options[:response_format] || 'url',
-      }.to_json
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
-        http.request(request)
-      end
-
-      if response.code == '200'
-        if options[:response_format] == 'base64'
-          image_base64 = JSON.parse(response.body)['data'][0]['base64']
-          return { image_base64: image_base64 }
-        else
-          image_url = JSON.parse(response.body)['data'][0]['url']
-          return { image_url: image_url }
-        end
-      else
-        raise RequestFailed, "Failed to generate image. Response code: #{response.code}. Response body: #{response.body}"
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative "generate_image/version"
+require_relative "generate_image/errors"
+require_relative "generate_image/configuration"
+require_relative "generate_image/models"
+require_relative "generate_image/response"
+require_relative "generate_image/http"
+require_relative "generate_image/client"
+
+module GenerateImage
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/scripts/gem-docker.cmd

@@ -0,0 +1,5 @@
+@echo off
+setlocal
+REM Run from repo root: scripts\gem-docker.cmd build | push
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0gem-docker.ps1" %*
+exit /b %ERRORLEVEL%