getimg_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88f3306bcd0b08d90484dd83f9a8bb613d303cbfd4999d0b14177cd44c072037
+  data.tar.gz: 2d557e3cda0acd3099ea52e7cf77f7d1e9eee330b9264c7f95e62ff759e8bcd4
+SHA512:
+  metadata.gz: 8954fbd6faa0b69b939303e9a9174121f039b11449e14dd7bb866c5adc9049b460bab4ea84ab4a98114d20504d6a1a9e0a5ea598204aaf4c84837d59c5cfbd02
+  data.tar.gz: 7b42386867ab12876da580ce9337510a86dd764fbf4fc8d427f5f3b11e73ecb1bb4259e6234540a0f2098e5d7feb70e29f219217b7e001337cfaada41cdd86b5

data/README.md

@@ -0,0 +1,119 @@
+# GetimgClient
+
+## Introduction
+GetimgClient is a Ruby gem designed to interact with the Getimg.ai API, enabling users to generate, manipulate, and enhance images using various AI models. This gem simplifies the process of making API requests to Getimg.ai, allowing for seamless integration of image generation and manipulation capabilities into your Ruby applications.
+
+## Functions
+
+### `set_api_key(api_key)`
+Set or override the API key used for authentication with the Getimg.ai API. This key can also be set by providing the **GETIMG_API_KEY** environment variable.
+
+### `retrieve_models`
+Fetch and cache the list of available models from the API.
+
+### `models`
+Retrieve cached models or fetch them if not already retrieved.
+
+### `generate_image(prompt, model:, **options)`
+Generate an image based on a text prompt and specified model. Supports various image manipulation methods such as image-to-image, inpainting, controlnet, face fixing, and upscaling.
+
+### `get_balance`
+Retrieve the current account balance from the Getimg.ai API.
+
+## Request Routing
+The `generate_image` method routes requests based on the provided options and the model's supported pipelines:
+- **text-to-image**: Default if no images are provided.
+- **image-to-image**: Triggered if a base image is provided.
+- **inpaint**: Triggered if a mask image is provided.
+- **controlnet**: Triggered if controlnet options are provided.
+- **face-fix**: Triggered if the model supports face-fix and a base image is provided.
+- **upscale**: Triggered if the model supports upscale and a base image is provided.
+
+## Parameters
+Parameters for `generate_image` and other methods are consistent with the official Getimg.ai API documentation. For detailed parameter descriptions, refer to the [official API documentation](https://docs.getimg.ai/reference/introduction).
+
+## Error Reporting
+Errors in the `GetimgClient` are handled through exceptions. The `handle_response` method is used to process API responses, raising errors when necessary:
+
+- **ArgumentError**: Raised for invalid arguments or unknown models.
+- **StandardError**: Raised for HTTP errors or API response errors.
+
+API errors are captured from the JSON response and included in the raised exception message. This includes both HTTP status errors and specific API error messages. For example:
+
+```ruby
+raise StandardError, "Error: #{result['error']['message']} (code: #{result['error']['code']})"
+```
+
+If an HTTP error occurs, the error message will include both the HTTP status and the error message from the API response, if available.
+
+### Models
+The provided `model` option will determine the model use, and contribute to the client's inference of the desired endpoint. Models can be the string `id` listed online at [the GetImg dashboard](https://dashboard.getimg.ai/models) or retrieved using the `GetimgClient.models` method. Equally, you can use symbols instead. For example, `:realistic_vision_v5_1` will translate to `'realistic-vision-v5-1'`
+
+### Base Image Options
+The `base_image` option can be provided, which will automatically set the "image" property for image-to-image, controlnet, face-fix, upscale and inpaint calls, and can be either a file path or a base64 encoded string of the file contents.
+
+### Results
+If all went well and no errors were reported, the response will be equal to the API response received, and thus align with the official documentation. Typically, this will be a hash containing an `image` property with the Base64 encoded image contents, a `seed` property with the generation's seed value, and a `cost` property with the usage cost for the generation.
+
+## Code Samples
+
+### Set API Key
+```ruby
+GetimgClient.set_api_key('your_api_key')
+```
+
+### Generate Text-to-Image
+```ruby
+result = GetimgClient.generate_image("A scenic landscape", model: :stable_diffusion_v1_5, width: 512, height: 512)
+puts result["image"]
+```
+
+### Generate Image-to-Image
+```ruby
+base_image = "path/to/base_image.jpg"
+result = GetimgClient.generate_image("Enhance the scene", model: :stable_diffusion_v1_5, base_image:, strength: 0.7)
+puts result["image"]
+```
+
+### Generate an image using Controlnet
+```ruby
+base_image = "path/to/base_image.jpg"
+result = GetimgClient.generate_image("Enhance the scene", model: :stable_diffusion_v1_5, base_image:, strength: 0.7, controlnet: canny-1.1)
+puts result["image"]
+```
+
+### Generate Inpainting
+```ruby
+base_image = Base64.strict_encode64(File.read("path/to/base_image.jpg"))
+mask_image = Base64.strict_encode64(File.read("path/to/mask_image.jpg"))
+result = GetimgClient.generate_image("Fill the white area with sky", model: :stable_diffusion_v1_5_inpainting, base_image:, mask_image_path: mask_image)
+puts result["image"]
+```
+
+### Face Fix
+```ruby
+base_image = Base64.strict_encode64(File.read("path/to/base_image.jpg"))
+result = GetimgClient.generate_image("Fix faces", model: :gfpgan_v1_3, base_image:)
+puts result["image"]
+```
+
+### Upscale
+```ruby
+base_image = Base64.strict_encode64(File.read("path/to/base_image.jpg"))
+result = GetimgClient.generate_image("Upscale image", model: :real_esrgan_4x, base_image:, scale: 4)
+puts result["image"]
+```
+
+### Logging
+Request logging will automatically be enabled, if the **RAILS_ENV** environment variable is set to "development"
+
+### Unit Testing
+The gem includes unit tests using Minitest. Integration tests make real API calls and will incur usage fees. Ensure your API key is set in the environment before running tests.
+
+To run the integration tests:
+
+```bash
+GETIMG_API_KEY=your_api_key rake integration
+```
+
+Integration test images are stored in the tmp directory for review.

data/lib/getimg_client.rb

@@ -0,0 +1,208 @@
+class GetimgClient
+  require 'base64'
+  require 'net/http'
+  require 'json'
+  require 'uri'
+
+  # Load the API endpoints from a JSON file
+  API_ENDPOINTS = JSON.parse(File.read(File.join(__dir__, 'endpoints.json'))).freeze
+
+  # Initialize the API key from environment variable
+  @api_key = ENV['GETIMG_API_KEY']
+
+  # Set or override the API key
+  def self.set_api_key(api_key)
+    @api_key = api_key
+  end
+
+  # Retrieve models from the API
+  def self.retrieve_models
+    uri = URI(API_ENDPOINTS['models'])
+    request = Net::HTTP::Get.new(uri)
+    request['Authorization'] = "Bearer #{@api_key}"
+    request['accept'] = 'application/json'
+
+    response = make_get_request(uri, request)
+    @models = parse_models_response(response)
+  end
+
+  # Get models, retrieving them if not already fetched
+  def self.models
+    @models ||= retrieve_models
+  end
+
+  # Generate an image based on the prompt and model
+  def self.generate_image(prompt, model:, **options)
+    # Validate the prompt
+    raise ArgumentError, 'Prompt is required' unless prompt.is_a?(String) && !prompt.strip.empty?
+
+    # Extract image paths from options
+    base_image = options.delete(:base_image)
+    mask_image_path = options.delete(:mask_image_path)
+    controlnet = options.delete(:controlnet)
+
+    # Convert model to appropriate ID format
+    model_id = model.to_s.gsub('_', '-')
+    model_info = models[model_id] || raise(ArgumentError, "Unknown model: #{model}")
+
+    # Determine the requested pipeline
+    requested_pipeline = method_requested(base_image, mask_image_path, controlnet, model_info).to_s.gsub('_', '-')
+
+    # Check if the model supports the requested pipeline
+    unless model_info[:pipelines].include?(requested_pipeline)
+      raise ArgumentError, "#{model_info[:name]} does not support #{requested_pipeline}"
+    end
+
+    # Determine the endpoint key based on the model family and pipeline
+    endpoint_key = determine_endpoint_key(model_info, requested_pipeline)
+    uri = URI(API_ENDPOINTS[endpoint_key.to_s])
+
+    # Handle image to image, controlnet, instruct, inpaint, face-fix, and upscale pipelines
+    if %w[image-to-image controlnet instruct inpaint face-fix upscale].include?(requested_pipeline)
+      image_base64 = validate_file_or_base64(base_image)
+      options.merge!(image: image_base64)
+      options.merge!(controlnet: controlnet) if requested_pipeline == 'controlnet'
+      if requested_pipeline == 'inpaint'
+        mask_image_base64 = validate_file_or_base64(mask_image_path)
+        options.merge!(mask_image: mask_image_base64)
+      end
+    end
+
+    # Ensure scale is an integer if present
+    options[:scale] = options[:scale].to_i if options[:scale]
+
+    # Logging request details in development environment
+    if ENV['RAILS_ENV'] == 'development'
+      puts "Generating image with the following details:"
+      puts "Prompt: #{prompt}"
+      puts "Model: #{model_id}"
+      puts "Requested Pipeline: #{requested_pipeline}"
+      puts "Endpoint URI: #{uri}"
+      truncated_options = options.transform_values { |v| v.is_a?(String) && v.length > 50 ? "#{v[0, 50]}..." : v }
+      puts "Options: #{truncated_options}"
+    end
+
+    # Create and send the request
+    request = create_request(uri, prompt, model: model_id, **options)
+    response = make_post_request(uri, request)
+    handle_response(response)
+  end
+
+  # Retrieve the current account balance
+  def self.get_balance
+    uri = URI(API_ENDPOINTS['balance'])
+    request = Net::HTTP::Get.new(uri)
+    request['Authorization'] = "Bearer #{@api_key}"
+    request['accept'] = 'application/json'
+
+    response = make_get_request(uri, request)
+    handle_response(response)
+  end
+
+  private
+
+  # Determine the requested method based on provided image paths, controlnet, and model_info
+  def self.method_requested(base_image, mask_image_path, controlnet, model_info)
+    return :controlnet if controlnet
+    return :inpaint if mask_image_path
+    return :instruct if model_info[:pipelines].include?('instruct') # Adjusting for instruct model
+    return :face_fix if base_image && !mask_image_path && !controlnet && model_info[:pipelines].include?('face-fix')
+    return :upscale if base_image && !mask_image_path && !controlnet && model_info[:pipelines].include?('upscale')
+    return :image_to_image if base_image
+    :text_to_image
+  end
+
+  # Determine the appropriate endpoint key based on the model family and pipeline
+  def self.determine_endpoint_key(model_info, requested_pipeline)
+    if model_info[:family] == 'stable-diffusion-xl'
+      return :sdxl_image_to_image if requested_pipeline == 'image-to-image'
+      return :sdxl_inpaint if requested_pipeline == 'inpaint'
+      return :sdxl_text_to_image
+    elsif model_info[:family] == 'latent-consistency'
+      return :lcm_image_to_image if requested_pipeline == 'image-to-image'
+      return :lcm_text_to_image
+    else
+      return requested_pipeline.gsub('-', '_').to_sym
+    end
+  end
+
+  # Create an HTTP POST request with the given parameters
+  def self.create_request(uri, prompt, model:, **options)
+    request = Net::HTTP::Post.new(uri)
+    request['Authorization'] = "Bearer #{@api_key}"
+    request['accept'] = 'application/json'
+    request['content-type'] = 'application/json'
+
+    body = {
+      prompt: prompt,
+      model: model
+    }.merge(options)
+
+    request.body = body.to_json
+    request
+  end
+
+  # Make an HTTP POST request
+  def self.make_post_request(uri, request)
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(request)
+    end
+  end
+
+  # Make an HTTP GET request
+  def self.make_get_request(uri, request)
+    Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      http.request(request)
+    end
+  end
+
+  # Handle the API response, raising errors if present
+  def self.handle_response(response)
+    case response
+    when Net::HTTPSuccess
+      result = JSON.parse(response.body)
+      if result['error']
+        raise StandardError, "Error: #{result['error']['message']} (code: #{result['error']['code']})"
+      end
+      result
+    else
+      error_message = "HTTP Error: #{response.message} (code: #{response.code})"
+      verbose_message = JSON.parse(response.body)['error']['message'] rescue nil
+      error_message += " - #{verbose_message}" if verbose_message
+      raise StandardError, error_message
+    end
+  end
+
+  # Validate if the input is a valid file path or base64 string
+  def self.validate_file_or_base64(input)
+    if File.exist?(input)
+      Base64.strict_encode64(File.read(input))
+    elsif input.match?(/\A([A-Za-z0-9+\/]{4})*([A-Za-z0-9+\/]{3}=|[A-Za-z0-9+\/]{2}==)?\z/)
+      input
+    else
+      raise ArgumentError, 'Invalid file path or base64 string'
+    end
+  end
+
+  # Parse the response from the models API to extract model details
+  def self.parse_models_response(response)
+    models = {}
+    case response
+    when Net::HTTPSuccess
+      JSON.parse(response.body).each do |model|
+        models[model['id']] = {
+          name: model['name'],
+          family: model['family'],
+          pipelines: model['pipelines'],
+          base_resolution: model['base_resolution'],
+          price: model['price'],
+          author_url: model['author_url'],
+          license_url: model['license_url']
+        }
+      end
+    else
+      raise StandardError, "HTTP Error: #{response.message} (code: #{response.code})"
+    end
+    models
+  end
+end

data/test/integration/getimg_client_integration_test.rb

@@ -0,0 +1,68 @@
+require_relative "../test_helper"
+
+class GetimgClientIntegrationTest < Minitest::Test
+  def setup
+    @base_image = Base64.strict_encode64(File.read(File.join(__dir__, "sample_image.jpeg")))
+
+    @small_image = Base64.strict_encode64(File.read(File.join(__dir__, "small_sample_image.jpeg")))
+
+    @mask_image = Base64.strict_encode64(File.read(File.join(__dir__, "mask_image.jpeg")))
+  end
+
+  def test_generate_text_to_image
+    puts "-- Running test_generate_text_to_image..."
+    result = GetimgClient.generate_image("A scenic landscape", model: :stable_diffusion_v1_5, width: 512, height: 512)
+    assert result["image"]
+    save_image(result["image"], "test_generate_text_to_image")
+  end
+
+  def test_generate_image_to_image
+    puts "-- Running test_generate_image_to_image..."
+    result = GetimgClient.generate_image("Enhance the scene", model: :stable_diffusion_v1_5, base_image: @base_image)
+    assert result["image"]
+    save_image(result["image"], "test_generate_image_to_image")
+  end
+
+  def test_generate_controlnet
+    puts "-- Running test_generate_controlnet..."
+    result = GetimgClient.generate_image("Outline of a landscape", model: :stable_diffusion_v1_5, base_image: @base_image, controlnet: "canny-1.1")
+    assert result["image"]
+    save_image(result["image"], "test_generate_controlnet")
+  end
+
+  def test_generate_instruct
+    puts "-- Running test_generate_instruct..."
+    result = GetimgClient.generate_image("Make it night time", model: :instruct_pix2pix, base_image: @base_image)
+    assert result["image"]
+    save_image(result["image"], "test_generate_instruct")
+  end
+
+  def test_generate_inpaint
+    puts "-- Running test_generate_inpaint..."
+    result = GetimgClient.generate_image("Fill the white area with sky", model: :stable_diffusion_v1_5_inpainting, base_image: @base_image, mask_image_path: @mask_image)
+    assert result["image"]
+    save_image(result["image"], "test_generate_inpaint")
+  end
+
+  def test_face_fix
+    puts "-- Running test_face_fix..."
+    result = GetimgClient.generate_image("Fix faces", model: :gfpgan_v1_3, base_image: @base_image)
+    assert result["image"]
+    save_image(result["image"], "test_face_fix")
+  end
+
+  def test_upscale
+    puts "-- Running test_upscale..."
+    result = GetimgClient.generate_image("Upscale image", model: :real_esrgan_4x, base_image: @small_image, scale: 4)
+    assert result["image"]
+    save_image(result["image"], "test_upscale")
+  end
+
+  private
+
+  def save_image(base64_image, filename)
+    File.open(File.join(__dir__, "../../tmp/#{filename}.jpeg"), "wb") do |file|
+      file.write(Base64.decode64(base64_image.split(",").last))
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require "minitest/autorun"
+require "getimg_client"

data/test/unit/getimg_client_test.rb

@@ -0,0 +1,13 @@
+require_relative "../test_helper"
+
+class GetimgClientTest < Minitest::Test
+  def test_retrieve_models
+    models = GetimgClient.retrieve_models
+    assert models.any?
+  end
+
+  def test_get_balance
+    balance = GetimgClient.get_balance
+    assert balance["amount"]
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: getimg_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Melvin Sommer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-06-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+description: A Ruby client for interfacing with the Getimg API.
+email:
+- sommer.melvin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/getimg_client.rb
+- test/integration/getimg_client_integration_test.rb
+- test/integration/mask_image.jpeg
+- test/integration/sample_image.jpeg
+- test/integration/small_sample_image.jpeg
+- test/test_helper.rb
+- test/unit/getimg_client_test.rb
+homepage: https://gitlab.com/coeusit/getimg_client
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Client for Getimg API
+test_files:
+- test/integration/getimg_client_integration_test.rb
+- test/integration/mask_image.jpeg
+- test/integration/sample_image.jpeg
+- test/integration/small_sample_image.jpeg
+- test/test_helper.rb
+- test/unit/getimg_client_test.rb