imago 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ab8cd4f924113a9ba92f0f6918b137c0132ebda6fe9d8d2006a62e158d1f987
+  data.tar.gz: 78f6726394dac041f2d82d1e068012767c94a616267801ac4cf597540e070884
+SHA512:
+  metadata.gz: d9b288487b3d77b17b70fe5289a9b63744e454f2bf01358304b846e0eb6cef28326287ac319887a1e539ea7f15a16ad22fc19f6579da47118d0fa6685b8d51e0
+  data.tar.gz: 2f3d13bd6d3bce751755c6a41e333139413cc28a1f31e6fde0c09c7671a592a9d87d731336200733112ad15d4886376708c48f25decf1008126866615d6f8bfa

data/.rubocop.yml

@@ -0,0 +1,48 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+Capybara:
+  Enabled: false
+
+Capybara/RSpec:
+  Enabled: false
+
+Capybara/RSpec/PredicateMatcher:
+  Enabled: false
+
+FactoryBot:
+  Enabled: false
+
+RSpecRails:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+Layout/LineLength:
+  Max: 120
+
+RSpec/MessageSpies:
+  EnforcedStyle: receive

data/.ruby-version

@@ -0,0 +1 @@
+ruby-4.0.0

data/README.md

@@ -0,0 +1,190 @@
+# Imago
+
+A unified Ruby interface for multiple image generation AI providers. Generate images using OpenAI (DALL-E), Google Gemini (Imagen), and xAI (Grok) through a single, consistent API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'imago'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install imago
+```
+
+## Configuration
+
+Set API keys via environment variables:
+
+```bash
+export OPENAI_API_KEY="your-openai-key"
+export GEMINI_API_KEY="your-gemini-key"
+export XAI_API_KEY="your-xai-key"
+```
+
+Or pass them directly when creating a client.
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'imago'
+
+# Create a client for OpenAI
+client = Imago.new(provider: :openai)
+
+# Generate an image
+result = client.generate("A serene mountain landscape at sunset")
+puts result[:images].first[:url]
+```
+
+### Specifying a Model
+
+```ruby
+# Use a specific model
+client = Imago.new(provider: :openai, model: 'dall-e-2')
+
+result = client.generate("A cat wearing a hat")
+```
+
+### Passing API Key Directly
+
+```ruby
+client = Imago.new(
+  provider: :openai,
+  api_key: 'sk-your-api-key'
+)
+```
+
+### Provider-Specific Options
+
+Each provider supports different options:
+
+#### OpenAI (DALL-E)
+
+```ruby
+client = Imago.new(provider: :openai)
+
+result = client.generate("A futuristic city", {
+  size: '1024x1024',      # '256x256', '512x512', '1024x1024', '1792x1024', '1024x1792'
+  quality: 'hd',          # 'standard' or 'hd'
+  n: 1,                   # Number of images (1-10)
+  response_format: 'url'  # 'url' or 'b64_json'
+})
+
+# Access the generated image
+result[:images].each do |image|
+  puts image[:url]
+  puts image[:revised_prompt]  # DALL-E 3 may revise your prompt
+end
+```
+
+#### Google Gemini (Imagen)
+
+```ruby
+client = Imago.new(provider: :gemini)
+
+result = client.generate("A tropical beach", {
+  n: 1,                        # Number of images
+  aspect_ratio: '16:9',        # Aspect ratio
+  negative_prompt: 'people',   # What to exclude
+  seed: 12345                  # For reproducibility
+})
+
+# Gemini returns base64-encoded images
+result[:images].each do |image|
+  puts image[:base64]
+  puts image[:mime_type]
+end
+```
+
+#### xAI (Grok)
+
+```ruby
+client = Imago.new(provider: :xai)
+
+result = client.generate("A robot playing chess", {
+  n: 1,
+  response_format: 'url'  # 'url' or 'b64_json'
+})
+
+result[:images].each do |image|
+  puts image[:url]
+end
+```
+
+### Listing Available Models
+
+```ruby
+client = Imago.new(provider: :openai)
+
+# Returns available image generation models
+models = client.models
+# => ["dall-e-3", "dall-e-2", "gpt-image-1"]
+```
+
+For providers with a models API (OpenAI, Gemini), this fetches from the API and caches the result. For providers without such an endpoint (xAI), it returns a curated list of known models.
+
+## Supported Providers
+
+Model list last updated: 01/18/2026.
+
+| Provider | Models | API Key Env Var |
+|----------|--------|-----------------|
+| OpenAI | `dall-e-3`, `dall-e-2`, `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | `OPENAI_API_KEY` |
+| Gemini | `imagen-3.0-generate-002`, `imagen-3.0-generate-001`, `gemini-2.0-flash-exp-image-generation`, `gemini-2.5-flash-image`, `gemini-3-pro-image-preview` | `GEMINI_API_KEY` |
+| xAI | `grok-2-image`, `grok-2-image-1212` | `XAI_API_KEY` |
+
+## Error Handling
+
+Imago provides specific error classes for different failure scenarios:
+
+```ruby
+begin
+  client = Imago.new(provider: :openai)
+  result = client.generate("A cat")
+rescue Imago::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Imago::RateLimitError => e
+  puts "Rate limited: #{e.message}"
+rescue Imago::InvalidRequestError => e
+  puts "Bad request: #{e.message}"
+rescue Imago::ApiError => e
+  puts "API error: #{e.message}"
+  puts "Status code: #{e.status_code}"
+rescue Imago::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+rescue Imago::ProviderNotFoundError => e
+  puts "Unknown provider: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests. You can also run `rake rubocop` for linting.
+
+```bash
+bundle install
+bundle exec rake spec      # Run tests
+bundle exec rake rubocop   # Run linter
+bundle exec rake           # Run both
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[rubocop spec]

data/imago.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/imago/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'imago'
+  spec.version = Imago::VERSION
+  spec.authors = ['Your Name']
+  spec.email = ['your.email@example.com']
+
+  spec.summary = 'A unified Ruby interface for multiple image generation AI providers'
+  spec.description = 'Imago provides a simple, unified API to generate images using various AI providers ' \
+                     'including OpenAI (DALL-E), Google Gemini, and xAI (Grok).'
+  spec.homepage = 'https://github.com/example/imago'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.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 do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?('bin/', 'test/', 'spec/', 'features/', '.git', '.github', 'appveyor', 'Gemfile')
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-multipart', '~> 1.0'
+end

data/lib/imago/client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Imago
+  class Client
+    PROVIDERS = {
+      openai: Providers::OpenAI,
+      gemini: Providers::Gemini,
+      xai: Providers::XAI
+    }.freeze
+
+    attr_reader :provider, :model
+
+    def initialize(provider:, model: nil, api_key: nil)
+      @provider_name = provider.to_sym
+      @model = model
+      @api_key = api_key
+
+      validate_provider!
+      @provider = build_provider
+    end
+
+    def generate(prompt, opts = {})
+      provider.generate(prompt, opts)
+    end
+
+    def models
+      provider.models
+    end
+
+    private
+
+    def validate_provider!
+      return if PROVIDERS.key?(@provider_name)
+
+      raise ProviderNotFoundError, "Unknown provider: #{@provider_name}. " \
+                                   "Available providers: #{PROVIDERS.keys.join(', ')}"
+    end
+
+    def build_provider
+      PROVIDERS[@provider_name].new(model: @model, api_key: @api_key)
+    end
+  end
+end

data/lib/imago/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Imago
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+
+  class RateLimitError < ApiError; end
+
+  class InvalidRequestError < ApiError; end
+
+  class ProviderNotFoundError < Error; end
+end

data/lib/imago/providers/base.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Imago
+  module Providers
+    class Base
+      attr_reader :model, :api_key
+
+      def initialize(model: nil, api_key: nil)
+        @model = model || default_model
+        @api_key = api_key || fetch_api_key
+        validate_api_key!
+      end
+
+      def generate(_prompt, _opts = {})
+        raise NotImplementedError, "#{self.class} must implement #generate"
+      end
+
+      def models
+        raise NotImplementedError, "#{self.class} must implement #models"
+      end
+
+      protected
+
+      def default_model
+        raise NotImplementedError, "#{self.class} must implement #default_model"
+      end
+
+      def env_key_name
+        raise NotImplementedError, "#{self.class} must implement #env_key_name"
+      end
+
+      def fetch_api_key
+        ENV.fetch(env_key_name, nil)
+      end
+
+      def validate_api_key!
+        return if api_key && !api_key.empty?
+
+        raise ConfigurationError,
+              "API key is required. Set #{env_key_name} environment variable or pass api_key option."
+      end
+
+      def connection(base_url)
+        Faraday.new(url: base_url) do |conn|
+          conn.request :json
+          conn.response :json
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        return response.body if response.status.between?(200, 299)
+
+        raise_response_error(response)
+      end
+
+      def raise_response_error(response)
+        error_class = error_class_for_status(response.status)
+        message = error_message_for_status(response)
+        raise error_class.new(message, status_code: response.status, response_body: response.body)
+      end
+
+      def error_class_for_status(status)
+        case status
+        when 401 then AuthenticationError
+        when 429 then RateLimitError
+        when 400..499 then InvalidRequestError
+        else ApiError
+        end
+      end
+
+      def error_message_for_status(response)
+        case response.status
+        when 401 then 'Invalid API key'
+        when 429 then 'Rate limit exceeded'
+        when 400..499 then "Request failed: #{response.body}"
+        else "API error: #{response.body}"
+        end
+      end
+    end
+  end
+end

data/lib/imago/providers/gemini.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Imago
+  module Providers
+    class Gemini < Base
+      BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'
+
+      KNOWN_IMAGE_MODELS = %w[
+        imagen-3.0-generate-002
+        imagen-3.0-generate-001
+        gemini-2.0-flash-exp-image-generation
+        gemini-2.5-flash-image
+        gemini-3-pro-image-preview
+      ].freeze
+
+      def generate(prompt, opts = {})
+        conn = connection(BASE_URL)
+        endpoint = "models/#{model}:generateContent"
+
+        response = conn.post(endpoint) do |req|
+          req.params['key'] = api_key
+          req.body = build_request_body(prompt, opts)
+        end
+
+        parse_generate_response(handle_response(response))
+      end
+
+      def models
+        @models ||= fetch_models
+      end
+
+      protected
+
+      def default_model
+        'gemini-3-pro-image-preview'
+      end
+
+      def env_key_name
+        'GEMINI_API_KEY'
+      end
+
+      private
+
+      def build_request_body(prompt, opts)
+        body = { contents: [{ parts: [{ text: build_prompt(prompt, opts) }] }] }
+        body[:generationConfig] = build_generation_config(opts) if generation_config_present?(opts)
+        body
+      end
+
+      def build_prompt(prompt, opts)
+        return prompt unless opts[:negative_prompt]
+
+        "#{prompt}. Avoid: #{opts[:negative_prompt]}"
+      end
+
+      def generation_config_present?(opts)
+        opts[:n] || opts[:sample_count] || opts[:aspect_ratio] || opts[:seed]
+      end
+
+      def build_generation_config(opts)
+        config = {}
+        config[:candidateCount] = opts[:sample_count] || opts[:n] if opts[:n] || opts[:sample_count]
+        config[:seed] = opts[:seed] if opts[:seed]
+        config[:aspectRatio] = opts[:aspect_ratio] if opts[:aspect_ratio]
+        config
+      end
+
+      def parse_generate_response(body)
+        candidates = body['candidates'] || []
+        images = candidates.flat_map { |candidate| extract_images_from_candidate(candidate) }
+        { images: images }
+      end
+
+      def extract_images_from_candidate(candidate)
+        parts = candidate.dig('content', 'parts') || []
+        parts.filter_map do |part|
+          next unless part['inlineData']
+
+          { base64: part['inlineData']['data'], mime_type: part['inlineData']['mimeType'] }.compact
+        end
+      end
+
+      def fetch_models
+        conn = connection(BASE_URL)
+        response = conn.get('models') do |req|
+          req.params['key'] = api_key
+        end
+
+        body = handle_response(response)
+        filter_image_models(body['models'] || [])
+      rescue ApiError
+        KNOWN_IMAGE_MODELS
+      end
+
+      def filter_image_models(models)
+        image_model_names = models
+                            .select { |m| m['supportedGenerationMethods']&.include?('generateContent') }
+                            .map { |m| m['name'].sub('models/', '') }
+                            .select { |name| name.include?('imagen') || name.include?('image') }
+
+        image_model_names.empty? ? KNOWN_IMAGE_MODELS : image_model_names
+      end
+    end
+  end
+end

data/lib/imago/providers/openai.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Imago
+  module Providers
+    class OpenAI < Base
+      BASE_URL = 'https://api.openai.com/v1'
+
+      KNOWN_IMAGE_MODELS = %w[
+        dall-e-3
+        dall-e-2
+        gpt-image-1
+        gpt-image-1.5
+        gpt-image-1-mini
+      ].freeze
+
+      def generate(prompt, opts = {})
+        conn = connection(BASE_URL)
+        response = conn.post('images/generations') do |req|
+          req.headers['Authorization'] = "Bearer #{api_key}"
+          req.body = build_request_body(prompt, opts)
+        end
+
+        parse_generate_response(handle_response(response))
+      end
+
+      def models
+        @models ||= fetch_models
+      end
+
+      protected
+
+      def default_model
+        'gpt-image-1.5'
+      end
+
+      def env_key_name
+        'OPENAI_API_KEY'
+      end
+
+      private
+
+      def build_request_body(prompt, opts)
+        {
+          model: model,
+          prompt: prompt
+        }.merge(opts)
+      end
+
+      def parse_generate_response(body)
+        images = body['data']&.map { |img| parse_image(img) }
+        { images: images || [], created: body['created'] }
+      end
+
+      def parse_image(img)
+        { url: img['url'], base64: img['b64_json'], revised_prompt: img['revised_prompt'] }.compact
+      end
+
+      def fetch_models
+        conn = connection(BASE_URL)
+        response = conn.get('models') do |req|
+          req.headers['Authorization'] = "Bearer #{api_key}"
+        end
+
+        body = handle_response(response)
+        filter_image_models(body['data'] || [])
+      rescue ApiError
+        KNOWN_IMAGE_MODELS
+      end
+
+      def filter_image_models(models)
+        image_model_ids = models
+                          .map { |m| m['id'] }
+                          .select { |id| id.include?('dall-e') || id.include?('image') }
+
+        image_model_ids.empty? ? KNOWN_IMAGE_MODELS : image_model_ids
+      end
+    end
+  end
+end

data/lib/imago/providers/xai.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Imago
+  module Providers
+    class XAI < Base
+      BASE_URL = 'https://api.x.ai/v1'
+
+      KNOWN_IMAGE_MODELS = %w[
+        grok-2-image
+        grok-2-image-1212
+      ].freeze
+
+      def generate(prompt, opts = {})
+        conn = connection(BASE_URL)
+        response = conn.post('images/generations') do |req|
+          req.headers['Authorization'] = "Bearer #{api_key}"
+          req.body = build_request_body(prompt, opts)
+        end
+
+        parse_generate_response(handle_response(response))
+      end
+
+      def models
+        KNOWN_IMAGE_MODELS
+      end
+
+      protected
+
+      def default_model
+        'grok-2-image'
+      end
+
+      def env_key_name
+        'XAI_API_KEY'
+      end
+
+      private
+
+      def build_request_body(prompt, opts)
+        {
+          model: model,
+          prompt: prompt,
+          n: opts[:n] || 1,
+          response_format: opts[:response_format] || 'url'
+        }.merge(opts.except(:n, :response_format))
+      end
+
+      def parse_generate_response(body)
+        images = body['data']&.map do |img|
+          {
+            url: img['url'],
+            base64: img['b64_json']
+          }.compact
+        end
+
+        {
+          images: images || [],
+          created: body['created']
+        }
+      end
+    end
+  end
+end

data/lib/imago/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Imago
+  VERSION = '0.1.1'
+end

data/lib/imago.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+require_relative 'imago/version'
+require_relative 'imago/errors'
+require_relative 'imago/providers/base'
+require_relative 'imago/providers/openai'
+require_relative 'imago/providers/gemini'
+require_relative 'imago/providers/xai'
+require_relative 'imago/client'
+
+module Imago
+  class << self
+    def new(provider:, model: nil, api_key: nil)
+      Client.new(provider: provider, model: model, api_key: api_key)
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: imago
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Your Name
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Imago provides a simple, unified API to generate images using various
+  AI providers including OpenAI (DALL-E), Google Gemini, and xAI (Grok).
+email:
+- your.email@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- README.md
+- Rakefile
+- imago.gemspec
+- lib/imago.rb
+- lib/imago/client.rb
+- lib/imago/errors.rb
+- lib/imago/providers/base.rb
+- lib/imago/providers/gemini.rb
+- lib/imago/providers/openai.rb
+- lib/imago/providers/xai.rb
+- lib/imago/version.rb
+homepage: https://github.com/example/imago
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/example/imago
+  source_code_uri: https://github.com/example/imago
+  changelog_uri: https://github.com/example/imago/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A unified Ruby interface for multiple image generation AI providers
+test_files: []