generate_image 1.1.2.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a39a12cd27cb300882eb79857d8134d8540b81da7bc9945bb80eaeb3543437
-  data.tar.gz: 9f3193a18e24feed900d736b64da907b8c2e92207f192082e9ffabf53bfcd7d2
+  metadata.gz: e70209150d3dca1a233b163e8d93db0d2251aa27252dd11a095549f51028652e
+  data.tar.gz: 31a17a9edd81b26e3d481b069c878c866072a80fc802e4b8af40c8b15954af89
 SHA512:
-  metadata.gz: 1c42a905340cb42f504dfb34ac8d342c6c36bc21efcdcf5dd4b1884962ae7d6a8f1c730bd98b5f515894e2d968abd4b143f7bea89aea13557aec817e2cd3dd9d
-  data.tar.gz: ebdb5c5fb2664d6945123a6bd3562ff8e7c10c78a077cd5952ca9cac2603955a59ca8dcf29e46eb7da5bee514cc1edc8eea20845587d991a9df5b26f95d4c50c
+  metadata.gz: 40a6e474de330720930bf1295ce9c7122611886dbeef1b7a021fa7339e2b35e03a23c77237a3de29de10827930ac7e049ab86c39c48d5f55ba64f268efea165a
+  data.tar.gz: 4918a9fec6f0fc57483ffe5940ad1a3bbee3810683b19fc065b19dbf6a523d2e2ce4f06114dfc7016d77ff830a6f1ca42ef8608c493d6c5ecefb0ffab28c1337

data/.env.example

@@ -0,0 +1,6 @@
+# Copy to .env (do not commit .env). Used by scripts/gem-docker.ps1 for `push` only.
+# RubyGems: https://rubygems.org/profile/edit → API key → paste here
+GEM_HOST_API_KEY=rubygems_YOUR_KEY_HERE
+
+# Optional: one-time MFA code for non-interactive push (never store long-term)
+# GEM_HOST_OTP_CODE=123456

data/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ["3.1", "3.2", "3.3"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Bundle install
+        run: bundle install
+      - name: RSpec
+        run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,14 @@
+*.gem
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.env

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.0
+before_install: gem install bundler -v 2.1.4

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-04-07
+
+### Added
+
+- `GenerateImage.configure` for global defaults (`api_key`, `default_model`, `base_url`, `default_size`, `default_quality`, `default_output_format`, timeouts, `max_retries`).
+- `GenerateImage::Client#generate` — `POST /v1/images/generations` with GPT Image models (`gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini`) and DALL·E 2/3.
+- `GenerateImage::Client#edit` — `POST /v1/images/edits` with multipart uploads (`image`, optional `mask`).
+- `GenerateImage::Response` with `#url`, `#b64`, `#images`, `#usage`, `#model`, `#raw`, `#to_h` (legacy-shaped hash).
+- Error types: `AuthenticationError`, `RateLimitError`, `ApiError`, `ValidationError`; `RequestFailed` aliases `ApiError` for rescues.
+- Retries on HTTP 429 using `Retry-After` (up to `configuration.max_retries`).
+- RSpec suite with WebMock.
+
+### Changed
+
+- **Default model** is `gpt-image-1` (was DALL·E 2–era `image-alpha-001`).
+- **Default size** is `1024x1024` (was `512x512`).
+- Preferred API key env var is **`OPENAI_API_KEY`**; **`DALL_E_API_KEY`** remains a fallback.
+
+### Removed
+
+- Runtime dependencies on `sinatra`, `openai`, and pinned `json` / `net-http` (stdlib `net/http` + `json` only).
+
+### Deprecated
+
+- `Client#generate_image` — use `#generate`; emits a deprecation warning on stderr.
+
+### Migration
+
+- Replace `client.generate_image("prompt", opts)` with `client.generate("prompt", **opts)` and use `Response` (`#url` / `#b64`) or `#to_h` for a v1-like hash.
+
+---
+
+## [1.x]
+
+Earlier releases targeted the legacy Images API with DALL·E 2 defaults. OpenAI has announced sunset timelines for older image models; prefer GPT Image models in new code.
+
+[2.0.0]: https://github.com/merouaneamqor/generate_image/releases

data/CLAUDE.md

@@ -0,0 +1,25 @@
+# generate_image — AI assistant notes
+
+Ruby gem: **OpenAI Images API** client (`/v1/images/generations`, `/v1/images/edits`). Stdlib only (`Net::HTTP`, `json`). **Ruby >= 3.1**.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `lib/generate_image.rb` | Entry; `GenerateImage.configure` |
+| `lib/generate_image/client.rb` | `#generate`, `#edit`, deprecated `#generate_image` |
+| `lib/generate_image/http.rb` | JSON POST, multipart POST, 429 retry |
+| `lib/generate_image/configuration.rb` | Keys, defaults, timeouts |
+| `lib/generate_image/models.rb` | Model/size constants |
+| `lib/generate_image/response.rb` | Parsed API response |
+| `lib/generate_image/errors.rb` | Error hierarchy |
+
+## Conventions
+
+- Do not add heavy runtime deps; keep generation HTTP in `HTTP`, validation in `Client`.
+- Preserve backward compat: `DALL_E_API_KEY` fallback, `RequestFailed` alias, `#generate_image` delegation.
+- API key: never log or persist keys; read from config or env only.
+
+## Checks
+
+From gem root: `bundle install` then `bundle exec rspec`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at marouane.amqor6@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    generate_image (1.1.2.2)
+      json (~> 2.6.3)
+      net-http (~> 0.3.2)
+      openai (~> 0.3.0)
+      sinatra (~> 3.0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.5.0)
+    json (2.6.3)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
+    net-http (0.3.2)
+      uri
+    openai (0.3.0)
+    rack (2.2.6.2)
+    rack-protection (3.0.5)
+      rack
+    rake (12.3.3)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    ruby2_keywords (0.0.5)
+    sinatra (3.0.5)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.0.5)
+      tilt (~> 2.0)
+    tilt (2.0.11)
+    uri (0.12.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  generate_image!
+  rake (~> 12.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2023 AMQOR Merouane
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2023-2026 AMQOR Merouane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,85 +1,165 @@
-# GenerateImage
-The GenerateImage gem is a Ruby gem that provides an interface for generating images using the OpenAI DALL-E API. This gem can be used in Ruby on Rails projects or any other Ruby projects.
-
-## Installation
-Add this line to your application's Gemfile:
-
-    gem 'generate_image'
-
-And then execute:
-
-    bundle install
-
-Or install it directly by running:
-
-    gem install generate_image
-## Usage
-The gem provides a generate_image method, which takes a text argument and returns the generated image URL or image base64 as a hash. The method makes a request to the DALL-E API to generate an image based on the provided text.
-
-Before using the generate_image method, you must set your OpenAI API key as an environment variable named DALL_E_API_KEY. The gem uses the Net::HTTP library to make API requests and includes error handling to ensure successful image generation. In case of any errors, the method will raise a RequestFailed exception.
-
-### Examples
-
-    require 'generate_image'
-
-    # Set the DALL-E API key
-    ENV['DALL_E_API_KEY'] = 'your_api_key'
-
-    # Generate a single image with default options
-    result = GenerateImage.generate_image('A three-story castle made of ice cream')
-    if result[:error]
-      puts result[:error]
-    else
-      puts result[:image_url]
-    end
-
-    # Generate a single image with custom options
-    result = GenerateImage.generate_image('A cat playing the piano', model: 'image-alpha-001', num_images: 2, size: '1024x1024', response_format: 'base64', quality: 90)
-    if result[:error]
-      puts result[:error]
-    else
-      puts result[:image_base64]
-    end
-## Options
-The generate_image method accepts a hash of options to customize the generated images. Here are the available options:
-
-`model` - The name of the model to use for generating the images. Default is `image-alpha-001`.
-
-`num_images` - The number of images to generate. Default is `1`.
-
-`size` - The dimensions of the generated images in the format widthxheight. Default is `512x512`.
-
-`response_format` - The format of the response, either `url` or `base64`. Default is `url`.
-
-`style` - The model or style to use for generating the images. Default is `nil`, which uses the default style of the selected model.
-
-`scale` - The scaling factor for the generated image. Default is `1`.
-
-`seed` - The random seed to use for the generation process. Default is `nil`.
-
-`quality` - The JPEG compression quality of the generated image. Default is `80`.
-
-`text_model` - The name of the model to use for generating text prompts. Default is `text-davinci-002`.
-
-`text_prompt` - The text prompt to use for generating the image. Default is `nil`.
-
-`text_length` - The maximum length of the generated text. Default is `nil`.
-
-## Development
-To contribute to the development of this gem, clone the repository and run the following commands to install dependencies and run tests:
-
-    bin/setup
-    rake spec
-You can also run bin/console for an interactive prompt to experiment with the code.
-
-To release a new version, update the version number in version.rb and run:
-
-    bundle exec rake release
-
-This will create a git tag for the new version, push the git commits and tags, and upload the .gem file to RubyGems.org.
-
-## Contributing
-Bug reports and pull requests are welcome on the GitHub repository. This project is intended to be a safe and welcoming space for collaboration, and all contributors are expected to adhere to the code of conduct.
-
-## License
-The GenerateImage gem is open source software, released under the terms of the MIT License.
+# GenerateImage
+
+Lightweight **Ruby** client for the **OpenAI Images API**: image generation (`POST /v1/images/generations`) and edits (`POST /v1/images/edits`). Uses only the standard library (`Net::HTTP`, `JSON`). **Ruby >= 3.1**.
+
+> **Deprecation / sunset (OpenAI):** DALL·E 2 and DALL·E 3 are scheduled for **sunset on May 12, 2026**. Prefer **GPT Image** models (`gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini`) for new integrations. This gem defaults to `gpt-image-1`.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "generate_image", "~> 2.0"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Set **`OPENAI_API_KEY`** (recommended). The legacy **`DALL_E_API_KEY`** is still read as a fallback if `OPENAI_API_KEY` is unset.
+
+Optional global defaults:
+
+```ruby
+require "generate_image"
+
+GenerateImage.configure do |c|
+  c.api_key = ENV["OPENAI_API_KEY"]
+  c.default_model = "gpt-image-1"
+  c.base_url = "https://api.openai.com"
+  c.default_size = "1024x1024"
+  c.default_quality = "auto"
+  c.default_output_format = "png"
+  c.open_timeout = 30
+  c.read_timeout = 120
+  c.max_retries = 1 # extra attempts after HTTP 429, honors Retry-After
+end
+```
+
+You can also pass an API key per client: `GenerateImage::Client.new("sk-...")`.
+
+## Usage
+
+### Generate (GPT Image)
+
+```ruby
+client = GenerateImage::Client.new
+
+response = client.generate("A ruby gemstone on velvet, product photo")
+
+response.b64        # first image base64 (typical for GPT Image)
+response.url        # first HTTPS URL when API returns URLs
+response.images     # => [{ b64_json: "..." }] or [{ url: "..." }], ...
+response.usage      # token usage hash or nil
+response.model      # model used
+response.raw        # full parsed JSON Hash
+```
+
+Common options (passed as keyword args):
+
+| Option | GPT Image | DALL·E 3 |
+|--------|-----------|----------|
+| `model` | `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | `dall-e-3` |
+| `n` | 1–10 | 1 only |
+| `size` | `auto`, `1024x1024`, `1536x1024`, `1024x1536` | `1024x1024`, `1792x1024`, `1024x1792` |
+| `quality` | `auto`, `high`, `medium`, `low` | `standard`, `hd` |
+| `output_format` | `png`, `jpeg`, `webp` | (API returns URLs by default; use `response_format`) |
+| `background` | `transparent`, `opaque`, `auto` | — |
+| `response_format` | `url`, `b64_json` if you need to force format | often `url` |
+
+```ruby
+client.generate(
+  "Minimal logo",
+  model: "gpt-image-1-mini",
+  size: "1024x1024",
+  quality: "high",
+  output_format: "png",
+  background: "transparent",
+  n: 2
+)
+```
+
+### Generate (DALL·E 3)
+
+```ruby
+client.generate(
+  "Sunset over the Atlantic",
+  model: "dall-e-3",
+  size: "1792x1024",
+  quality: "hd",
+  response_format: "url"
+)
+```
+
+### Edit / inpainting
+
+Multipart request with at least **`image:`** (path string, `Pathname`, `IO`, or `StringIO`) and **`prompt:`**.
+
+```ruby
+client.edit(
+  image: "input.png",
+  prompt: "Add soft studio lighting",
+  model: "gpt-image-1",
+  size: "1024x1024",
+  quality: "auto",
+  mask: "mask.png" # optional
+)
+```
+
+Additional GPT Image–oriented options: `output_format`, `background`, `input_fidelity` (`high` / `low`), `response_format`, `user`.
+
+### Errors
+
+| Exception | When |
+|-----------|------|
+| `GenerateImage::AuthenticationError` | 401 / missing API key |
+| `GenerateImage::RateLimitError` | 429 (retried according to `max_retries` and `Retry-After`) |
+| `GenerateImage::ApiError` | Other non-success HTTP responses (`#status_code`, `#body`) |
+| `GenerateImage::ValidationError` | Invalid prompt, model/size/n combination, etc. |
+
+`GenerateImage::RequestFailed` is an alias for `ApiError` for compatibility with rescues from v1.x.
+
+## Backward compatibility (v1.x)
+
+- `client.generate_image(text, options_hash)` still works but **prints a deprecation warning** and returns a legacy-shaped `Hash` (`:image_url` or `:image_base64`) via `Response#to_h`.
+- Legacy keys: `num_images` → `n`, `response_format: "base64"` → `b64_json` for the API.
+
+Prefer:
+
+```ruby
+response = client.generate("A cat")
+response.url || response.b64
+```
+
+## Migration from 1.x
+
+1. Bump Ruby to **3.1+** and gem to **~> 2.0**.
+2. Set **`OPENAI_API_KEY`** (keep `DALL_E_API_KEY` temporarily if needed).
+3. Replace `generate_image(...)` with `generate(...)` and read `Response` fields instead of only a Hash.
+4. Update defaults mentally: model is **`gpt-image-1`**, size **`1024x1024`**, not DALL·E 2 `512x512` / `image-alpha-001`.
+5. Plan for **DALL·E 2/3 sunset (May 12, 2026)** — move prompts to GPT Image models.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Interactive console:
+
+```bash
+bin/console
+```
+
+## Contributing
+
+Issues and pull requests are welcome on the [GitHub repository](https://github.com/merouaneamqor/generate_image).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -1,14 +1,14 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "generate_image"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "generate_image"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +1,8 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here