reve_ai 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 280bf1673c22b411163ea4dad09eae4a7ca07a06dceefee1d10b54cc2a07a097
-  data.tar.gz: 288d3493fcd73b1827003b785c29fd0c7ce53a76a302769e03054686508d2dc4
+  metadata.gz: a51cf5f511364f9b5420edaba5d26f020c533354706dc0777fcd50a73ac8b99e
+  data.tar.gz: 15d846e877511007e0cf82ab1d447bf1915482dfa31210e8c4e7180aa75c6032
 SHA512:
-  metadata.gz: 604e38817990a60d470e0c24b96033c88b27774012e6dac07e6392c7f413d02fd8c123a92978868eb972790dea4ad23f11ce73226c11db88f0c3a5482aff7e52
-  data.tar.gz: 202c65bafdcd96b002cff7a083f10b7efd4c05e187b0add59831833e8d6dfd88e7aa0fac49037b986a5aedb4bcf19eceb3b6d4a679741a2acb3bd7577bc5a27f
+  metadata.gz: b6af6528d75a2ab2fb007cf4e2e6277c722cc34d9ac396643e75bf3d36e09db4ff450764fc3f3c8d0cffa27f0a7e6cabc65f189a36c92d8b4ee8e313e257d4f2
+  data.tar.gz: 99194027f16869e1a2ecea152a030bb1a54f7d7e60b91824e608b7e9e41c5b82da12d5fdcdc633e54f5dd498a883e133ea3420725df8f9250593688bcb3728d4

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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).
+
+## [0.2.0] - Unreleased
+
+### 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
+
+- Initial release
+- `ReveAI::Client` for API authentication and configuration
+- Image generation via `client.images.generate`
+- Image editing via `client.images.edit`
+- Image remix via `client.images.remix`
+- Automatic retry with exponential backoff via Faraday
+- Configurable timeouts and base URL

data/README.md

@@ -37,6 +37,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 +88,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 +116,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 +388,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 +419,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,6 +459,12 @@ bundle exec rake test
 bundle exec rubocop
 ```
 
+## Release  
+
+```sh 
+bundle exec rake release
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/reve_ai.

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
 

data/lib/reve_ai/http/client.rb

@@ -39,12 +39,46 @@ module ReveAI
         @configuration = configuration
       end
 
+      # Makes a GET request to the API.
+      #
+      # @param path [String] API endpoint path (e.g., "/v1/image/effect")
+      # @param params [Hash, nil] Query parameters to merge into the URL
+      #   (e.g., { source: "project" })
+      #
+      # @return [Response] Parsed API response
+      #
+      # @raise [TimeoutError] if request times out
+      # @raise [ConnectionError] if connection fails
+      # @raise [NetworkError] for other network errors
+      # @raise [BadRequestError] on 400 responses
+      # @raise [UnauthorizedError] on 401 responses
+      # @raise [InsufficientCreditsError] on 402 responses
+      # @raise [ForbiddenError] on 403 responses
+      # @raise [NotFoundError] on 404 responses
+      # @raise [UnprocessableEntityError] on 422 responses
+      # @raise [RateLimitError] on 429 responses
+      # @raise [ServerError] on 5xx responses
+      #
+      # @api private
+      def get(path, params: nil)
+        normalized_path = path.sub(%r{^/}, "")
+        response = perform_request do |conn|
+          conn.get(normalized_path) { |req| req.params.update(params) if params }
+        end
+        handle_response(response)
+      end
+
       # Makes a POST request to the API.
       #
       # @param path [String] API endpoint path (e.g., "/v1/image/create")
       # @param body [Hash] Request body to send as JSON
+      # @param params [Hash, nil] Query parameters to merge into the URL
+      #   (e.g., { breadcrumb: "my-tracking-value" })
+      # @param accept [String, nil] Per-request Accept header override
+      #   (e.g., "image/webp"). The connection default stays "application/json".
       #
-      # @return [Response] Parsed API response
+      # @return [Response] Parsed API response. When the response Content-Type
+      #   is +image/*+, the body is the raw image String (bytes), not a Hash.
       #
       # @raise [TimeoutError] if request times out
       # @raise [ConnectionError] if connection fails
@@ -59,10 +93,31 @@ module ReveAI
       # @raise [ServerError] on 5xx responses
       #
       # @api private
-      def post(path, body = {})
+      def post(path, body = {}, params: nil, accept: nil)
         normalized_path = path.sub(%r{^/}, "")
-        response = connection.post(normalized_path) { |req| req.body = JSON.generate(body) }
+        response = perform_request do |conn|
+          conn.post(normalized_path) do |req|
+            req.params.update(params) if params
+            req.headers["Accept"] = accept if accept
+            req.body = JSON.generate(body)
+          end
+        end
         handle_response(response)
+      end
+
+      private
+
+      # Performs an HTTP request, mapping Faraday errors to gem errors.
+      #
+      # @yieldparam connection [Faraday::Connection] Connection to perform the request on
+      # @return [Faraday::Response] Raw Faraday response
+      #
+      # @raise [TimeoutError] if request times out
+      # @raise [ConnectionError] if connection fails
+      # @raise [NetworkError] for other network errors
+      # @api private
+      def perform_request
+        yield connection
       rescue Faraday::TimeoutError => e
         raise TimeoutError, "Request timed out: #{e.message}"
       rescue Faraday::ConnectionFailed => e
@@ -71,8 +126,6 @@ module ReveAI
         raise NetworkError, "Network error: #{e.message}"
       end
 
-      private
-
       # Handles connection failed errors.
       #
       # Distinguishes between timeout errors (which may appear as connection failures)
@@ -116,7 +169,7 @@ module ReveAI
       # @api private
       def configure_retry(conn)
         conn.request :retry, max: configuration.max_retries, interval: 0.5,
-                             backoff_factor: 2, retry_statuses: RETRY_STATUSES, methods: [:post]
+                             backoff_factor: 2, retry_statuses: RETRY_STATUSES, methods: %i[post get]
       end
 
       # Configures request headers.
@@ -162,7 +215,7 @@ module ReveAI
       # @raise [APIError] on error responses
       # @api private
       def handle_response(response)
-        body = parse_body(response.body)
+        body = parse_body(response)
         return build_success_response(response, body) if response.status.between?(200, 299)
 
         raise_api_error(response.status, body, response.headers.to_h)
@@ -171,37 +224,66 @@ module ReveAI
       # Builds a successful response object.
       #
       # @param response [Faraday::Response] Raw response
-      # @param body [Hash] Parsed body
+      # @param body [Hash, String] Parsed body, or raw bytes for binary responses
       # @return [Response] Response wrapper
       # @api private
       def build_success_response(response, body)
         Response.new(status: response.status, headers: response.headers.to_h, body: body)
       end
 
-      # Parses the response body as JSON.
+      # Parses the response body.
+      #
+      # Bodies with an +image/*+ Content-Type are raw image bytes and are
+      # returned as-is; anything else is parsed as JSON.
       #
-      # @param body [String, nil] Raw response body
-      # @return [Hash] Parsed body, or empty hash if nil/empty
+      # @param response [Faraday::Response] Raw Faraday response
+      # @return [Hash, String] Parsed body, raw bytes String for image
+      #   responses, or empty hash if body is nil/empty
       # @api private
-      def parse_body(body)
-        return {} if body.nil? || body.empty?
+      def parse_body(response)
+        raw = response.body
+        return {} if raw.nil? || raw.empty?
+        return raw if image_content?(response)
 
-        JSON.parse(body, symbolize_names: true)
+        JSON.parse(raw, symbolize_names: true)
       rescue JSON::ParserError
-        { raw: body }
+        { raw: raw }
+      end
+
+      # Checks whether the response carries raw image bytes.
+      #
+      # @param response [Faraday::Response] Raw Faraday response
+      # @return [Boolean] true if Content-Type starts with "image/"
+      # @api private
+      def image_content?(response)
+        response.headers["content-type"].to_s.start_with?("image/")
       end
 
       # Raises the appropriate API error for a status code.
       #
       # @param status [Integer] HTTP status code
-      # @param body [Hash] Parsed response body
+      # @param body [Hash, String] Parsed response body
       # @param headers [Hash] Response headers
       # @raise [APIError] Appropriate error subclass
       # @api private
       def raise_api_error(status, body, headers)
         error_class = ERROR_CODE_MAP[status] || (status >= 500 ? ServerError : APIError)
-        message = body[:message] || body[:error] || "Unknown error"
-        raise error_class.new(message, status: status, body: body, headers: headers)
+        raise error_class.new(extract_error_message(body, headers), status: status, body: body, headers: headers)
+      end
+
+      # Extracts the error message from the response body.
+      #
+      # Falls back to the X-Reve-Error-Code header when the body carries no
+      # message: with an image Accept header, the API answers errors with a
+      # small grey image instead of a JSON error body.
+      #
+      # @param body [Hash, String] Parsed response body
+      # @param headers [Hash] Response headers
+      # @return [String] Error message
+      # @api private
+      def extract_error_message(body, headers)
+        from_body = body.is_a?(Hash) ? body[:message] || body[:error] : nil
+        from_body || headers["x-reve-error-code"] || "Unknown error"
       end
     end
   end