reve_ai 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3521245e81bb791e68e3bf8bbdd9d4f1c325b621a164e9126091cc7ec349ee99
-  data.tar.gz: fc4c447d73bf93ad39909b7c51c444b22fe393bb5aa06ba1300a3dac64171fcd
+  metadata.gz: 44c9a9191d46d7088bf8888415b2727f2e5587bfb3e6ff6f3d321225aa5f4dad
+  data.tar.gz: 1f16304c1c0fd6fc1751a34a6e0dd1853f6f4f4f1f5c48df13e9f50993bc1ae4
 SHA512:
-  metadata.gz: dbc3e027851edffb5dc34b1f53719855857f43f512f403ccac146a455d820798f67e40787b210cb46b6032030396b619f5f750875c7c9beebb411afd47d13886
-  data.tar.gz: 326cc725907f9275e966fdb34072bb03da90909b0d52ed376f092d701d7726bc9148697b8c08c997784fd4c9a6b60d58e2b4a0393fe00ceb4de312b3cb471c00
+  metadata.gz: 299ccdcdb8b24b512a165b9b4d765e2d4681b25fd0ddcb0649ed129442634dd68c5447d9b18980561308929e45516dfec95add5585e9304fe6b614cb67cedacd
+  data.tar.gz: 732e06bbe67ac1dd62aaff55bb97ab19406fb1b8c0ebf2a2c64141da183eeb0b3b77380720ff58af5954aa38c39bb4294f9e894acbcf84632f5110ea949f247c

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [0.2.1] - 2026-08-05
+
+### Deprecated
+
+- Documented the Reve public API shutdown and the gem's deprecated, unmaintained status
+- Added a RubyGems post-install warning with the API sunset date and repository README link
+
+## [0.2.0] - 2026-07-17
+
+### Added
+
+- API v2 image creation via `client.v2.images.create` (`POST /v2/image/create`): ordered `references`
+  (`{ data: }` / `{ ref: }` objects addressed from the prompt as `<frame>N</frame>`), the full
+  18-value aspect-ratio set including `auto`, prompts up to 4000 characters, and up to 8 references
+- Experimental layout endpoints under `client.v2.layouts`: `extract` (`POST /v2/image/extract_layout`),
+  `create` (`POST /v2/image/create_layout`), and `render` (`POST /v2/image/render_layout`)
+- Effects listing via `client.effects.list` (`GET /v1/image/effect`) with an optional `source` filter
+- `postprocessing:`, `test_time_scaling:`, `accept:`, and `breadcrumb:` options on the v1
+  `create`/`edit`/`remix` and v2 endpoints
+- Binary image responses: `accept: "image/png"`, `"image/jpeg"`, or `"image/webp"` returns raw image
+  bytes with metadata in `X-Reve-*` headers
+- `ImageResponse#layout` and `ReveAI::LayoutResponse` for the structured layouts returned by v2 endpoints
+- `APIError#params` for the error-specific `params` object returned by the API, and `APIError#error_code`
+  now falls back to the `X-Reve-Error-Code` header (binary error responses)
+- GET support in the HTTP layer; retries now cover GET requests as well as POST
+
+### Fixed
+
+- Remix `<img>N</img>` YARD documentation corrected to 0-based indexing, matching the API
+
 ## [0.1.0] - 2026-01-04
 
 ### Added

data/README.md

@@ -5,6 +5,12 @@ Ruby client for the [Reve image generation API](https://api.reve.com/console/doc
 [![Gem Version](https://badge.fury.io/rb/reve_ai.svg)](https://badge.fury.io/rb/reve_ai)
 [![ci](https://github.com/dpaluy/reve_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/reve_ai/actions/workflows/ci.yml)
 
+## API sunset notice
+
+> **Reve's public API sunsets Friday, August 14, 2026.** Existing approved API users retain access through the sunset window; all other users can no longer access it, and new API onboarding is closed. Unused paid credits begin full-refund processing Monday, August 17, 2026.
+
+This gem is deprecated and will be unmaintained after the API shutdown. No further feature development or maintenance is planned.
+
 ## Installation
 
 ```
@@ -37,6 +43,18 @@ response.credits_used   # => 18
 response.credits_remaining # => 982
 ```
 
+Save the image to a file:
+
+```ruby
+require "base64"
+
+image_data = Base64.decode64(response.image)
+
+File.open("output.png", "wb") do |f|
+  f.write(image_data)
+end
+```
+
 With aspect ratio:
 
 ```ruby
@@ -76,7 +94,7 @@ response.image   # => "base64editeddata..."
 response.version # => "reve-edit@20250915"
 ```
 
-Available versions for edit: `latest`, `latest-fast`, `reve-edit@20250915`, `reve-edit-fast@20251030`
+Available versions for edit: `latest`, `latest-fast`, `reve-edit@20250915`, `reve-edit-fast@20251030`, `reve-edit-passthrough@20260625`
 
 ### Remix Images
 
@@ -104,6 +122,227 @@ response.version # => "reve-remix@20250915"
 
 Available versions for remix: `latest`, `latest-fast`, `reve-remix@20250915`, `reve-remix-fast@20251030`
 
+### Postprocessing and Effects
+
+The v1 `create`/`edit`/`remix` methods and `client.v2.images.create` accept these optional keyword arguments (`client.v2.layouts.render` also supports `postprocessing:` and `accept:`, and every endpoint supports `breadcrumb:`):
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `postprocessing:` | Array of operation Hashes | Operations applied to the generated image (see below) |
+| `test_time_scaling:` | `1`-`15` | Spend more effort (and credits) on the request; clamped server-side. Not recommended for v2 models |
+| `accept:` | `"image/png"`, `"image/jpeg"`, `"image/webp"` | Return raw image bytes instead of JSON; metadata moves to `X-Reve-*` headers |
+| `breadcrumb:` | String | Request-tracking tag, searchable on the Reve Usage page; ignored by the API |
+
+Supported postprocessing operations:
+
+| Operation | Parameters | Notes |
+|-----------|------------|-------|
+| `upscale` | `upscale_factor` (integer, 1-4) | Adds credits cost; a 4x upscale is large |
+| `remove_background` | none | Adds credits cost; works best with a clear subject |
+| `fit_image` | `max_dim`, `max_width`, and/or `max_height` (max 4096) | Free; scales down preserving aspect ratio |
+| `effect` | `effect_name`, optional `effect_parameters` | Applies an effect saved in your project |
+
+```ruby
+response = client.images.create(
+  prompt: "A beautiful sunset over mountains",
+  postprocessing: [
+    { process: "upscale", upscale_factor: 2 },
+    { process: "fit_image", max_dim: 2048 }
+  ],
+  test_time_scaling: 3,
+  breadcrumb: "homepage-hero"
+)
+```
+
+Effect parameter overrides use a nested `{ filterId => { uniformId => value } }` format; omitted parameters fall back to the effect's saved defaults:
+
+```ruby
+response = client.images.create(
+  prompt: "A high-quality photo of a wine bottle",
+  postprocessing: [
+    {
+      process: "effect",
+      effect_name: "adjustments",
+      effect_parameters: {
+        "adjustments" => {
+          "u_exposure" => 42,
+          "u_contrast" => -38,
+          "u_vibrance" => 64
+        }
+      }
+    }
+  ]
+)
+```
+
+List the effects available to your project — the returned `name` values are valid `effect_name` arguments:
+
+```ruby
+response = client.effects.list
+
+response.body[:effects].each do |effect|
+  puts "#{effect[:name]} (#{effect[:source]})" # source: "saved" (project) or "builtin" (preset)
+end
+
+# Optional source filter: "all" (default), "project" (saved only), "preset" (builtin only)
+presets = client.effects.list(source: "preset")
+```
+
+### API v2
+
+The v2 API collapses the three v1 workflows into a single endpoint, `client.v2.images.create`, which takes ordered reference images and returns a structured `layout` alongside the image. The v1 endpoints above remain live and unchanged.
+
+- Prompts up to 4000 characters, and up to 8 reference images
+- The full 18-value aspect-ratio set, including `auto` (the default) — see [Validation Constraints](#validation-constraints)
+- References are objects with exactly one of `data:` (base64-encoded image) or `ref:` (`"id:<uuid>"` for a stored image or generation, `"reference:@<name>"` for a named project reference)
+- Address a reference from the prompt as `<frame>N</frame>` (0-based: the first reference is `<frame>0</frame>`)
+- v2 images are significantly larger than v1 — cap the output with a free `fit_image` step: `postprocessing: [{ process: "fit_image", max_dim: 2048 }]`
+
+Generate an image from text:
+
+```ruby
+response = client.v2.images.create(prompt: "A beautiful sunset over mountains")
+
+response.image   # => "base64encodeddata..."
+response.version # => "latest" (v2 responses currently always report "latest")
+```
+
+Edit an image (pass it as the first reference and address it as `<frame>0</frame>`):
+
+```ruby
+require "base64"
+
+image_data = Base64.strict_encode64(File.read("my-image.png"))
+
+response = client.v2.images.create(
+  prompt: "Add dramatic clouds to the sky of <frame>0</frame>",
+  references: [{ data: image_data }]
+)
+```
+
+Combine multiple references:
+
+```ruby
+person     = Base64.strict_encode64(File.read("person.png"))
+background = Base64.strict_encode64(File.read("background.png"))
+
+response = client.v2.images.create(
+  prompt: "The person from <frame>0</frame> standing in the scene from <frame>1</frame>",
+  references: [{ data: person }, { data: background }],
+  aspect_ratio: "21:9"
+)
+```
+
+Every v2 JSON response includes the layout the model generated for the image:
+
+```ruby
+response = client.v2.images.create(prompt: "A serene mountain landscape at sunset")
+
+response.layout # => { prompt: "...", regions: [...], width: 4672, height: 3520 }
+
+response.layout[:regions].each do |region|
+  puts "#{region[:label]}: #{region[:prompt]}"
+end
+```
+
+Request a binary image instead of JSON with `accept:` — `response.image` then holds the raw bytes, and the metadata arrives via `X-Reve-*` headers:
+
+```ruby
+response = client.v2.images.create(
+  prompt: "A beautiful sunset over mountains",
+  accept: "image/webp"
+)
+
+File.binwrite("mountains.webp", response.image) # no Base64 decoding needed
+
+response.credits_used # => 150
+```
+
+Pass `version:` to pin a model alias — v2 aliases observed: `latest` (default), `reve-v2-create@260601`.
+
+#### Migrating from v1 to v2
+
+All three v1 workflows map to `client.v2.images.create`:
+
+Create — keep `prompt` and `aspect_ratio`:
+
+```ruby
+# v1
+client.images.create(prompt: "A serene mountain landscape at sunset",
+                     aspect_ratio: "16:9", version: "latest")
+
+# v2
+client.v2.images.create(prompt: "A serene mountain landscape at sunset",
+                        aspect_ratio: "16:9")
+```
+
+Edit — the edited image becomes `references[0]`, addressed as `<frame>0</frame>`:
+
+```ruby
+# v1
+client.images.edit(edit_instruction: "Remove the people in the background.",
+                   reference_image: image_b64)
+
+# v2
+client.v2.images.create(prompt: "Remove the people in the background of <frame>0</frame>.",
+                        references: [{ data: image_b64 }])
+```
+
+Remix — `<img>N</img>` tags become `<frame>N</frame>` (both 0-based) and bare base64 strings become `{ data: }` objects:
+
+```ruby
+# v1
+client.images.remix(prompt: "The woman from <img>0</img> driving the car from <img>1</img>.",
+                    reference_images: [woman_b64, car_b64], aspect_ratio: "1:1")
+
+# v2
+client.v2.images.create(prompt: "The woman from <frame>0</frame> driving the car from <frame>1</frame>.",
+                        references: [{ data: woman_b64 }, { data: car_b64 }], aspect_ratio: "1:1")
+```
+
+#### Experimental Layout Endpoints
+
+The layout endpoints are **experimental**: they require care and experimentation to achieve good results, are best suited for agents and custom tooling, and may change. For simple generation and prompt-based editing, use `client.v2.images.create`. They return JSON only (`render` also supports `accept:`) and commonly take 10-40 seconds (`render`: 40-80 seconds) — keep timeouts at 120 seconds or more.
+
+A layout is a Hash with an optional overall `prompt`, optional `width`/`height`, and a `regions` array; each region carries a `label`, a regional `prompt`, and a normalized `bbox` (`x0`, `y0`, `x1`, `y1` in 0.0-1.0, top-left origin).
+
+Extract a layout from an image:
+
+```ruby
+image = { data: Base64.strict_encode64(File.read("photo.jpg")) }
+
+response = client.v2.layouts.extract(image: image)
+response.layout # => { prompt: "...", regions: [...], width: 4672, height: 3520 }
+```
+
+Create a layout from a prompt, without rendering an image:
+
+```ruby
+response = client.v2.layouts.create(prompt: "a person at a cafe", aspect_ratio: "3:2")
+layout = response.layout
+```
+
+Render an image from a layout:
+
+```ruby
+response = client.v2.layouts.render(layout: layout)
+response.image # => "base64encodeddata..."
+```
+
+Unlike v2 create, the layout endpoints take compound references — each entry may contain any subset of `image:`, `layout:`, and `prompt:`:
+
+```ruby
+response = client.v2.layouts.create(
+  prompt: "Put the bottle on a wooden table",
+  references: [
+    { image: { data: bottle_b64 }, prompt: "the product to feature" },
+    { layout: saved_layout }
+  ]
+)
+```
+
+`create` also accepts `commands:` — ordered imperative edits (`add`, `place`, `shift`, `remove`, `keep`, `change`) with normalized positions; see the [API docs](https://api.reve.com/console/docs) for the command shapes.
+
 ### Rails
 
 Create `config/initializers/reve_ai.rb`:
@@ -155,6 +394,19 @@ rescue ReveAI::ConnectionError => e
 end
 ```
 
+Every API error also exposes the details returned by the API:
+
+```ruby
+rescue ReveAI::APIError => e
+  e.error_code # => "PROMPT_TOO_LONG"
+  e.params     # => Hash of error-specific parameters, or nil
+  e.status     # => 400
+  e.request_id # => "rsid-..."
+end
+```
+
+For binary image requests (`accept: "image/*"`), error responses carry a small grey image and the error code arrives in the `X-Reve-Error-Code` header — `#error_code` reads it from either the response body or the header.
+
 ### Content Moderation
 
 The API may flag content violations:
@@ -173,20 +425,38 @@ end
 |--------|---------|-------------|
 | `api_key` | `ENV["REVE_AI_API_KEY"]` | Your Reve API key |
 | `base_url` | `https://api.reve.com` | API base URL |
-| `timeout` | `120` | Request timeout in seconds |
+| `timeout` | `120` | Request timeout in seconds (the API requires at least 120) |
 | `open_timeout` | `30` | Connection timeout in seconds |
 | `max_retries` | `2` | Number of retries for failed requests |
 | `logger` | `nil` | Logger instance for debugging |
 | `debug` | `false` | Enable debug logging |
 
+The API requires client timeouts of at least 120 seconds: image generation and rendering commonly take 40-80 seconds, and the layout endpoints 10-40 seconds. The gem's default of 120 seconds complies. Treat shorter client-side timeouts as cancellations — the server may still finish the request after the client disconnects.
+
 ### Validation Constraints
 
+v1 endpoints (`create`, `edit`, `remix`):
+
 | Constraint | Value |
 |------------|-------|
 | Max prompt length | 2560 characters |
 | Max reference images (remix) | 6 |
 | Valid aspect ratios | 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 1:1 |
 
+v2 endpoints (`client.v2`):
+
+| Constraint | Value |
+|------------|-------|
+| Max prompt length | 4000 characters |
+| Max reference images | 8 |
+| Valid aspect ratios | 4:1, 3:1, 21:9, 2:1, 17:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16, 1:2, 1:3, 1:4, auto (default: auto) |
+
+Input image limits (any endpoint that accepts images):
+
+- Formats: WEBP, JPEG, PNG, GIF, TIFF, AVIF — base64-encoded in JSON
+- Per image: at most 40 MB and 33,554,432 pixels, with neither dimension exceeding 8192 pixels
+- Per call: at most 100 MB and 50,331,648 pixels across all images
+
 ## Development
 
 ```
@@ -195,15 +465,13 @@ bundle exec rake test
 bundle exec rubocop
 ```
 
-## Release  
+## Release
 
-```sh 
-bundle exec rake release
-```
+This gem is deprecated, and no further feature releases are planned.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/reve_ai.
+This project is deprecated and will be unmaintained after the API shutdown. Contributions for new features or ongoing maintenance are no longer being accepted.
 
 ## License
 

data/lib/reve_ai/client.rb

@@ -64,13 +64,40 @@ module ReveAI
     #
     # @example Remix images
     #   result = client.images.remix(
-    #     prompt: "Combine <img>1</img> and <img>2</img> into one scene",
+    #     prompt: "Combine <img>0</img> and <img>1</img> into one scene",
     #     reference_images: [image1_base64, image2_base64]
     #   )
     def images
       @images ||= Resources::Images.new(self)
     end
 
+    # Returns the Effects resource for listing available effects.
+    #
+    # @return [Resources::Effects] Effects listing interface
+    # @see Resources::Effects
+    #
+    # @example List all effects available to the project
+    #   result = client.effects.list
+    #   result.body[:effects].each { |effect| puts effect[:name] }
+    def effects
+      @effects ||= Resources::Effects.new(self)
+    end
+
+    # Returns the v2 API namespace (image create and layout endpoints).
+    #
+    # @return [Resources::V2] v2 API operations interface
+    # @see Resources::V2
+    #
+    # @example Generate an image with the v2 API
+    #   result = client.v2.images.create(
+    #     prompt: "Remove the people in the background of <frame>0</frame>.",
+    #     references: [{ data: base64_encoded_image }]
+    #   )
+    #   result.layout # => { prompt: "...", regions: [...] }
+    def v2
+      @v2 ||= Resources::V2.new(self)
+    end
+
     # Returns the HTTP client for making API requests.
     #
     # @return [HTTP::Client] HTTP client instance

data/lib/reve_ai/configuration.rb

@@ -34,7 +34,7 @@ module ReveAI
     # @return [Integer] Default number of retry attempts for failed requests
     DEFAULT_MAX_RETRIES = 2
 
-    # @return [Array<String>] Valid aspect ratios for image generation
+    # @return [Array<String>] Valid aspect ratios for legacy v1 image generation
     VALID_ASPECT_RATIOS = %w[16:9 9:16 3:2 2:3 4:3 3:4 1:1].freeze
 
     # @return [Integer] Maximum allowed prompt length in characters
@@ -43,6 +43,15 @@ module ReveAI
     # @return [Integer] Maximum number of reference images for remix operations
     MAX_REFERENCE_IMAGES = 6
 
+    # @return [Array<String>] Valid aspect ratios for image generation
+    ASPECT_RATIOS = %w[4:1 3:1 21:9 2:1 17:9 16:9 3:2 4:3 5:4 1:1 4:5 3:4 2:3 9:16 1:2 1:3 1:4 auto].freeze
+
+    # @return [Integer] Maximum allowed prompt length in characters for v2 endpoints
+    V2_MAX_PROMPT_LENGTH = 4000
+
+    # @return [Integer] Maximum number of references for v2 create operations
+    V2_MAX_REFERENCES = 8
+
     # @return [String, nil] Reve API key for authentication
     attr_accessor :api_key
 

data/lib/reve_ai/errors.rb

@@ -72,22 +72,27 @@ module ReveAI
     # @return [Integer, nil] HTTP status code
     attr_reader :status
 
-    # @return [Hash] Response body parsed as Hash
+    # @return [Hash, String] Response body parsed as Hash, or raw String
+    #   for binary error responses (e.g., grey image bodies)
     attr_reader :body
 
     # @return [Hash] Response headers
     attr_reader :headers
 
+    # @return [Hash, nil] Additional error details from the response body
+    attr_reader :params
+
     # Creates a new API error instance.
     #
     # @param message [String, nil] Error message
     # @param status [Integer, nil] HTTP status code
-    # @param body [Hash, nil] Response body
+    # @param body [Hash, String, nil] Response body
     # @param headers [Hash, nil] Response headers
     def initialize(message = nil, status: nil, body: nil, headers: nil)
       @status = status
       @body = body || {}
       @headers = headers || {}
+      @params = @body.is_a?(Hash) ? @body[:params] : nil
       super(message)
     end
 
@@ -100,11 +105,17 @@ module ReveAI
       headers["x-reve-request-id"]
     end
 
-    # Returns the error code from the response body.
+    # Returns the error code for this error.
+    #
+    # Read from the response body when present, falling back to the
+    # X-Reve-Error-Code header: with an image Accept header, the API answers
+    # errors with a small grey image body and no JSON error code.
     #
     # @return [String, nil] Error code (e.g., "PROMPT_TOO_LONG", "INVALID_API_KEY")
     def error_code
-      body[:error_code]
+      return body[:error_code] if body.is_a?(Hash) && body[:error_code]
+
+      headers["x-reve-error-code"]
     end
   end