reve_ai 0.1.0 → 0.2.0

data/lib/reve_ai/resources/base.rb

@@ -41,26 +41,41 @@ module ReveAI
         client.configuration
       end
 
+      # Makes a GET request to the API.
+      #
+      # @param path [String] API endpoint path
+      # @param params [Hash, nil] Query parameters to merge into the URL
+      # @return [Response] API response
+      # @api private
+      def get(path, params: nil)
+        http_client.get(path, params: params)
+      end
+
       # Makes a POST request to the API.
       #
       # @param path [String] API endpoint path
       # @param body [Hash] Request body
+      # @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")
       # @return [Response] API response
       # @api private
-      def post(path, body = {})
-        http_client.post(path, body)
+      def post(path, body = {}, params: nil, accept: nil)
+        http_client.post(path, body, params: params, accept: accept)
       end
 
       # Validates a text prompt.
       #
       # @param prompt [String] The prompt to validate
       # @param field_name [String] Name for error messages (default: "Prompt")
+      # @param max_length [Integer] Maximum allowed length in characters
+      #   (default: v1 limit of {Configuration::MAX_PROMPT_LENGTH})
       # @raise [ValidationError] if prompt is nil, empty, or exceeds max length
       # @api private
-      def validate_prompt!(prompt, field_name: "Prompt")
+      def validate_prompt!(prompt, field_name: "Prompt", max_length: Configuration::MAX_PROMPT_LENGTH)
         raise ValidationError, "#{field_name} is required" if prompt.nil? || prompt.empty?
 
-        max_length = Configuration::MAX_PROMPT_LENGTH
         return unless prompt.length > max_length
 
         raise ValidationError, "#{field_name} exceeds maximum length of #{max_length} characters"
@@ -69,17 +84,58 @@ module ReveAI
       # Validates an aspect ratio value.
       #
       # @param aspect_ratio [String, nil] The aspect ratio to validate
+      # @param valid_ratios [Array<String>] Allowed aspect ratios
+      #   (default: v1 set {Configuration::VALID_ASPECT_RATIOS})
       # @raise [ValidationError] if aspect ratio is invalid
       # @api private
-      def validate_aspect_ratio!(aspect_ratio)
+      def validate_aspect_ratio!(aspect_ratio, valid_ratios = Configuration::VALID_ASPECT_RATIOS)
         return if aspect_ratio.nil?
-
-        valid_ratios = Configuration::VALID_ASPECT_RATIOS
         return if valid_ratios.include?(aspect_ratio)
 
         raise ValidationError, "Invalid aspect_ratio '#{aspect_ratio}'. Must be one of: #{valid_ratios.join(", ")}"
       end
 
+      # Validates a postprocessing steps array.
+      #
+      # @param postprocessing [Array<Hash>, nil] Postprocessing steps, each
+      #   requiring a +process+ key (e.g., { process: "upscale", upscale_factor: 2 })
+      # @raise [ValidationError] if not an Array of Hashes, or a step lacks a +process+ key
+      # @api private
+      def validate_postprocessing!(postprocessing)
+        return if postprocessing.nil?
+
+        unless postprocessing_steps?(postprocessing)
+          raise ValidationError, "Postprocessing must be an Array of Hashes with a 'process' key"
+        end
+
+        postprocessing.each_with_index do |step, index|
+          next if step.key?(:process) || step.key?("process")
+
+          raise ValidationError, "Postprocessing step at index #{index} must include a 'process' key"
+        end
+      end
+
+      # Checks whether a value is an Array of Hashes (postprocessing shape).
+      #
+      # @param value [Object] The value to check
+      # @return [Boolean] true if value is an Array of Hashes
+      # @api private
+      def postprocessing_steps?(value)
+        value.is_a?(Array) && value.all?(Hash)
+      end
+
+      # Validates a test_time_scaling value.
+      #
+      # @param value [Numeric, nil] Scaling factor (1-15)
+      # @raise [ValidationError] if not a Numeric between 1 and 15
+      # @api private
+      def validate_test_time_scaling!(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && value.between?(1, 15)
+
+        raise ValidationError, "test_time_scaling must be a number between 1 and 15"
+      end
+
       # Validates a single reference image.
       #
       # @param image [String] Base64 encoded image data

data/lib/reve_ai/resources/effects.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ReveAI
+  module Resources
+    # Effects listing operations.
+    #
+    # Lists the effects available to the project associated with the API key,
+    # including saved project effects and built-in presets. Names from this
+    # list can be applied to any generation via the +postprocessing+ parameter
+    # of the image resources (see Images#create).
+    #
+    # @example List all effects
+    #   client = ReveAI::Client.new(api_key: "your-key")
+    #   result = client.effects.list
+    #   result.body[:effects].each { |effect| puts effect[:name] }
+    #
+    # @note The list returns effect names only — effect parameter definitions
+    #   are not included. Configure effect presets in the Reve application,
+    #   save them with a name, and apply that name from the API.
+    # @see https://api.reve.com/console/docs Reve API Documentation
+    class Effects < Base
+      # @return [String] API endpoint for listing effects
+      LIST_ENDPOINT = "/v1/image/effect"
+
+      # @return [Array<String>] Valid values for the +source+ filter
+      VALID_SOURCES = %w[all project preset].freeze
+
+      # Lists effects available to the project.
+      #
+      # The default response includes both saved project effects (+source+
+      # "saved") and built-in presets (+source+ "builtin"). Each entry in
+      # +body[:effects]+ carries +name+ and +source+, plus optional
+      # +description+ and +category+ (e.g., "color", "textures") when
+      # available. Use a returned +name+ as +effect_name+ in postprocessing
+      # requests.
+      #
+      # @param source [String, nil] Filter by effect origin: "all" (default),
+      #   "project" (saved project effects only), or "preset" (builtin only)
+      # @param breadcrumb [String, nil] Request tracking label sent as the
+      #   +breadcrumb+ query param; ignored by the API, searchable in the
+      #   Usage page
+      #
+      # @return [Response] Response whose +body[:effects]+ is an Array of
+      #   effect Hashes with +name+, +source+, and optional +description+
+      #   and +category+ keys
+      #
+      # @raise [ValidationError] if source is not one of "all", "project", "preset"
+      # @raise [UnauthorizedError] if API key is invalid
+      # @raise [RateLimitError] if rate limit is exceeded
+      #
+      # @example List all effects
+      #   result = client.effects.list
+      #   result.body[:effects].map { |effect| effect[:name] }
+      #
+      # @example List only saved project effects
+      #   result = client.effects.list(source: "project")
+      #
+      # @see https://api.reve.com/console/docs Reve API Documentation
+      def list(source: nil, breadcrumb: nil)
+        validate_source!(source)
+
+        params = {}
+        params[:source] = source if source
+        params[:breadcrumb] = breadcrumb if breadcrumb
+
+        get(LIST_ENDPOINT, params: params.empty? ? nil : params)
+      end
+
+      private
+
+      # Validates the source filter.
+      #
+      # @param source [String, nil] The source filter to validate
+      # @raise [ValidationError] if source is not one of {VALID_SOURCES}
+      # @api private
+      def validate_source!(source)
+        return if source.nil? || VALID_SOURCES.include?(source)
+
+        raise ValidationError, "Invalid source '#{source}'. Must be one of: #{VALID_SOURCES.join(", ")}"
+      end
+    end
+  end
+end

data/lib/reve_ai/resources/images.rb

@@ -23,11 +23,13 @@ module ReveAI
     #
     # @example Remix multiple images
     #   result = client.images.remix(
-    #     prompt: "Combine the style of <img>1</img> with the subject of <img>2</img>",
+    #     prompt: "Combine the style of <img>0</img> with the subject of <img>1</img>",
     #     reference_images: [style_image_base64, subject_image_base64]
     #   )
     #
-    # @note All images are returned as base64 encoded PNG data.
+    # @note By default all images are returned as base64 encoded PNG data;
+    #   pass accept: "image/png", "image/jpeg", or "image/webp" to any method
+    #   for raw image bytes instead (see method docs).
     # @see https://api.reve.com/console/docs Reve API Documentation
     class Images < Base
       # @return [String] API endpoint for image creation
@@ -44,6 +46,22 @@ module ReveAI
       # @param prompt [String] Text description of the desired image (max 2560 chars)
       # @param aspect_ratio [String, nil] Output aspect ratio (defaults to API default)
       # @param version [String, nil] Model version to use (defaults to "latest")
+      # @param postprocessing [Array<Hash>, nil] Postprocessing steps applied after
+      #   generation; each step requires a +process+ key:
+      #   +upscale+ (+upscale_factor+ 2-4, adds credits cost),
+      #   +remove_background+,
+      #   +fit_image+ (+max_dim+/+max_width+/+max_height+, max 4096, free),
+      #   +effect+ (+effect_name+, optional +effect_parameters+ overrides nested
+      #   as +{ filter_id: { uniform_id: value } }+)
+      # @param test_time_scaling [Numeric, nil] Effort scaling factor 1-15
+      #   (default 1); values above 1 add credits cost, values above 5 only
+      #   occasionally improve results
+      # @param accept [String, nil] Response format: "application/json" (default)
+      #   or "image/png", "image/jpeg", "image/webp" for raw image bytes, e.g.
+      #   accept: "image/webp" returns the raw image via result.image (metadata
+      #   moves to the X-Reve-* response headers)
+      # @param breadcrumb [String, nil] Request tracking label sent as the
+      #   +breadcrumb+ query param; ignored by the API, searchable in the Usage page
       #
       # @option aspect_ratio [String] "16:9" Widescreen landscape
       # @option aspect_ratio [String] "9:16" Portrait (phone)
@@ -53,10 +71,13 @@ module ReveAI
       # @option aspect_ratio [String] "3:4" Standard portrait
       # @option aspect_ratio [String] "1:1" Square
       #
-      # @return [ImageResponse] Response containing base64 encoded image
+      # @return [ImageResponse] Response containing base64 encoded image,
+      #   or raw image bytes when +accept+ is an image format
       #
       # @raise [ValidationError] if prompt is empty or exceeds max length
       # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [ValidationError] if postprocessing is not an Array of Hashes with a +process+ key
+      # @raise [ValidationError] if test_time_scaling is not a number between 1 and 15
       # @raise [BadRequestError] if API rejects the request
       # @raise [UnauthorizedError] if API key is invalid
       # @raise [InsufficientCreditsError] if account has no credits
@@ -71,20 +92,38 @@ module ReveAI
       #     aspect_ratio: "16:9"
       #   )
       #
+      # @example With postprocessing (upscale, then fit within 2048px)
+      #   result = client.images.create(
+      #     prompt: "A panoramic mountain landscape",
+      #     postprocessing: [{ process: "upscale", upscale_factor: 2 },
+      #                      { process: "fit_image", max_dim: 2048 }]
+      #   )
+      #
+      # @example Request raw WebP bytes instead of JSON
+      #   result = client.images.create(prompt: "A sunset", accept: "image/webp")
+      #   File.binwrite("sunset.webp", result.image) # raw bytes, no Base64 decode
+      #
       # @example Save to file
       #   result = client.images.create(prompt: "A sunset")
       #   File.binwrite("image.png", Base64.decode64(result.base64))
       #
       # @see https://api.reve.com/console/docs#/Image/create_v1_image_create_post
-      def create(prompt:, aspect_ratio: nil, version: nil)
+      def create(prompt:, aspect_ratio: nil, version: nil, postprocessing: nil, test_time_scaling: nil,
+                 accept: nil, breadcrumb: nil)
         validate_prompt!(prompt)
         validate_aspect_ratio!(aspect_ratio)
+        validate_postprocessing!(postprocessing)
+        validate_test_time_scaling!(test_time_scaling)
 
         body = { prompt: prompt }
         body[:aspect_ratio] = aspect_ratio if aspect_ratio
         body[:version] = version if version
+        body[:postprocessing] = postprocessing if postprocessing
+        body[:test_time_scaling] = test_time_scaling if test_time_scaling
+
+        params = breadcrumb ? { breadcrumb: breadcrumb } : nil
 
-        response = post(CREATE_ENDPOINT, body)
+        response = post(CREATE_ENDPOINT, body, params: params, accept: accept)
         ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
       end
 
@@ -94,12 +133,24 @@ module ReveAI
       # @param reference_image [String] Base64 encoded image to edit
       # @param aspect_ratio [String, nil] Output aspect ratio (defaults to reference image ratio)
       # @param version [String, nil] Model version to use (defaults to "latest")
+      # @param postprocessing [Array<Hash>, nil] Postprocessing steps applied after
+      #   generation; see {#create} for the supported step shapes
+      # @param test_time_scaling [Numeric, nil] Effort scaling factor 1-15
+      #   (default 1); values above 1 add credits cost
+      # @param accept [String, nil] Response format: "application/json" (default)
+      #   or "image/png", "image/jpeg", "image/webp" for raw image bytes via
+      #   result.image (metadata moves to the X-Reve-* response headers)
+      # @param breadcrumb [String, nil] Request tracking label sent as the
+      #   +breadcrumb+ query param; ignored by the API, searchable in the Usage page
       #
-      # @return [ImageResponse] Response containing base64 encoded edited image
+      # @return [ImageResponse] Response containing base64 encoded edited image,
+      #   or raw image bytes when +accept+ is an image format
       #
       # @raise [ValidationError] if edit_instruction is empty or exceeds max length
       # @raise [ValidationError] if reference_image is empty
       # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [ValidationError] if postprocessing is not an Array of Hashes with a +process+ key
+      # @raise [ValidationError] if test_time_scaling is not a number between 1 and 15
       # @raise [UnprocessableEntityError] if reference_image is not valid base64
       # @raise [BadRequestError] if API rejects the request
       # @raise [UnauthorizedError] if API key is invalid
@@ -116,67 +167,100 @@ module ReveAI
       #     reference_image: landscape_base64
       #   )
       #
+      # @example Remove the background after editing
+      #   result = client.images.edit(
+      #     edit_instruction: "Change the car color from red to blue",
+      #     reference_image: original_image_base64,
+      #     postprocessing: [{ process: "remove_background" }]
+      #   )
+      #
       # @see https://api.reve.com/console/docs#/Image/edit_v1_image_edit_post
-      def edit(edit_instruction:, reference_image:, aspect_ratio: nil, version: nil)
+      def edit(edit_instruction:, reference_image:, aspect_ratio: nil, version: nil, postprocessing: nil,
+               test_time_scaling: nil, accept: nil, breadcrumb: nil)
         validate_prompt!(edit_instruction, field_name: "Edit instruction")
         validate_reference_image!(reference_image)
+        validate_postprocessing!(postprocessing)
+        validate_test_time_scaling!(test_time_scaling)
 
         body = { edit_instruction: edit_instruction, reference_image: reference_image }
         body[:aspect_ratio] = aspect_ratio if aspect_ratio
         body[:version] = version if version
+        body[:postprocessing] = postprocessing if postprocessing
+        body[:test_time_scaling] = test_time_scaling if test_time_scaling
+
+        params = breadcrumb ? { breadcrumb: breadcrumb } : nil
 
-        response = post(EDIT_ENDPOINT, body)
+        response = post(EDIT_ENDPOINT, body, params: params, accept: accept)
         ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
       end
 
       # Creates a new image by remixing multiple reference images.
       #
       # Use `<img>N</img>` tags in the prompt to reference specific images,
-      # where N is the 1-based index into the reference_images array.
+      # where N is the 0-based index into the reference_images array.
       #
       # @param prompt [String] Text description with optional image references (max 2560 chars)
       # @param reference_images [Array<String>] Array of base64 encoded images (1-6 images)
       # @param aspect_ratio [String, nil] Output aspect ratio (defaults to model's choice)
       # @param version [String, nil] Model version to use (defaults to "latest")
+      # @param postprocessing [Array<Hash>, nil] Postprocessing steps applied after
+      #   generation; see {#create} for the supported step shapes
+      # @param test_time_scaling [Numeric, nil] Effort scaling factor 1-15
+      #   (default 1); values above 1 add credits cost
+      # @param accept [String, nil] Response format: "application/json" (default)
+      #   or "image/png", "image/jpeg", "image/webp" for raw image bytes via
+      #   result.image (metadata moves to the X-Reve-* response headers)
+      # @param breadcrumb [String, nil] Request tracking label sent as the
+      #   +breadcrumb+ query param; ignored by the API, searchable in the Usage page
       #
-      # @return [ImageResponse] Response containing base64 encoded remixed image
+      # @return [ImageResponse] Response containing base64 encoded remixed image,
+      #   or raw image bytes when +accept+ is an image format
       #
       # @raise [ValidationError] if prompt is empty or exceeds max length
       # @raise [ValidationError] if reference_images is empty or exceeds 6 images
       # @raise [ValidationError] if any reference image is empty
       # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [ValidationError] if postprocessing is not an Array of Hashes with a +process+ key
+      # @raise [ValidationError] if test_time_scaling is not a number between 1 and 15
       # @raise [BadRequestError] if API rejects the request
       #
       # @example Combine two images
       #   result = client.images.remix(
-      #     prompt: "Combine the landscape from <img>1</img> with the sky from <img>2</img>",
+      #     prompt: "Combine the landscape from <img>0</img> with the sky from <img>1</img>",
       #     reference_images: [landscape_base64, sky_base64]
       #   )
       #
       # @example Style transfer
       #   result = client.images.remix(
-      #     prompt: "Apply the artistic style of <img>1</img> to the photo <img>2</img>",
+      #     prompt: "Apply the artistic style of <img>0</img> to the photo <img>1</img>",
       #     reference_images: [artwork_base64, photo_base64]
       #   )
       #
       # @example Multiple references
       #   result = client.images.remix(
-      #     prompt: "Create a scene with the dog from <img>1</img>, " \
-      #             "the background from <img>2</img>, and lighting from <img>3</img>",
+      #     prompt: "Create a scene with the dog from <img>0</img>, " \
+      #             "the background from <img>1</img>, and lighting from <img>2</img>",
       #     reference_images: [dog_base64, background_base64, lighting_ref_base64]
       #   )
       #
       # @see https://api.reve.com/console/docs#/Image/remix_v1_image_remix_post
-      def remix(prompt:, reference_images:, aspect_ratio: nil, version: nil)
+      def remix(prompt:, reference_images:, aspect_ratio: nil, version: nil, postprocessing: nil,
+                test_time_scaling: nil, accept: nil, breadcrumb: nil)
         validate_prompt!(prompt)
         validate_reference_images!(reference_images)
         validate_aspect_ratio!(aspect_ratio)
+        validate_postprocessing!(postprocessing)
+        validate_test_time_scaling!(test_time_scaling)
 
         body = { prompt: prompt, reference_images: reference_images }
         body[:aspect_ratio] = aspect_ratio if aspect_ratio
         body[:version] = version if version
+        body[:postprocessing] = postprocessing if postprocessing
+        body[:test_time_scaling] = test_time_scaling if test_time_scaling
+
+        params = breadcrumb ? { breadcrumb: breadcrumb } : nil
 
-        response = post(REMIX_ENDPOINT, body)
+        response = post(REMIX_ENDPOINT, body, params: params, accept: accept)
         ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
       end
     end

data/lib/reve_ai/resources/v2/images.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module ReveAI
+  module Resources
+    class V2
+      # v2 image generation operations.
+      #
+      # The v2 create endpoint unifies the v1 create, edit, and remix
+      # workflows: a single prompt plus an ordered list of reference images.
+      # JSON responses include a structured +layout+ alongside the image.
+      #
+      # @example Generate an image from text
+      #   result = client.v2.images.create(prompt: "A sunset over mountains")
+      #   result.base64 # Base64 encoded PNG
+      #   result.layout # => { prompt: "...", regions: [...] }
+      #
+      # @note Image generation requests commonly take 40-80 seconds; the API
+      #   documentation mandates request timeouts of at least 120 seconds
+      #   (the gem default).
+      #
+      # @see https://api.reve.com/console/docs Reve API Documentation
+      class Images < Base
+        # @return [String] API endpoint for v2 image creation
+        CREATE_ENDPOINT = "/v2/image/create"
+
+        # Generates an image from a text prompt with optional reference images.
+        #
+        # Reference images are addressed from the prompt with `<frame>N</frame>`
+        # tags, where N is the 0-based index into the +references+ array (so
+        # the first reference is `<frame>0</frame>`).
+        #
+        # @param prompt [String] Text description of the desired image
+        #   (max 4000 chars); may contain `<frame>N</frame>` reference tags
+        # @param references [Array<Hash>, nil] Up to 8 reference images
+        #   ({Configuration::V2_MAX_REFERENCES}). Each entry is a Hash with
+        #   exactly one of +data+ (base64 encoded image String) or +ref+
+        #   (identifier String: +"id:<uuid>"+ for a previously stored image or
+        #   generation, +"reference:@<name>"+ for a named reference in your
+        #   project). Entries are serialized as given.
+        # @param aspect_ratio [String, nil] Output aspect ratio (defaults to
+        #   the API default of "auto", which lets the model pick); v2 supports
+        #   the full set in {Configuration::ASPECT_RATIOS}, including "auto"
+        #   and "4:1"
+        # @param postprocessing [Array<Hash>, nil] Postprocessing steps, each
+        #   with a +process+ key (e.g., { process: "upscale", upscale_factor: 2 })
+        # @param test_time_scaling [Numeric, nil] Scaling factor (1-15);
+        #   values above 1 cost more credits
+        # @param version [String, nil] Optional public model version alias,
+        #   passed through as-is (e.g., "latest", "reve-v2-create@260601")
+        # @param accept [String, nil] Per-request Accept header: "image/png",
+        #   "image/jpeg", or "image/webp" for a binary image response, or
+        #   "application/json" (default)
+        # @param breadcrumb [String, nil] Request tracking value sent as the
+        #   +breadcrumb+ query parameter; ignored by the API
+        #
+        # @return [ImageResponse] Response containing the image and, on JSON
+        #   responses, the generated +layout+
+        #
+        # @raise [ValidationError] if prompt is empty or exceeds 4000 characters
+        # @raise [ValidationError] if references is malformed or exceeds 8 entries
+        # @raise [ValidationError] if aspect_ratio is invalid
+        # @raise [ValidationError] if postprocessing or test_time_scaling is invalid
+        # @raise [BadRequestError] if API rejects the request
+        # @raise [UnauthorizedError] if API key is invalid
+        # @raise [InsufficientCreditsError] if account has no credits
+        # @raise [RateLimitError] if rate limit is exceeded
+        #
+        # @example Text-to-image (no references)
+        #   result = client.v2.images.create(
+        #     prompt: "A serene mountain landscape at sunset",
+        #     aspect_ratio: "16:9"
+        #   )
+        #
+        # @example Edit-style: one reference addressed as <frame>0</frame>
+        #   result = client.v2.images.create(
+        #     prompt: "Remove the people in the background of <frame>0</frame>.",
+        #     references: [{ data: original_image_base64 }]
+        #   )
+        #
+        # @example Remix-style: combine two references
+        #   result = client.v2.images.create(
+        #     prompt: "The woman from <frame>0</frame> driving the car from <frame>1</frame>.",
+        #     references: [{ data: woman_base64 }, { data: car_base64 }]
+        #   )
+        #
+        # @note v2 images are significantly larger than v1 images; the API
+        #   documentation suggests capping the output size with
+        #   +postprocessing: [{ process: "fit_image", max_dim: 2048 }]+.
+        # @note The API documentation does not recommend +test_time_scaling+
+        #   for v2 models.
+        #
+        # @see https://api.reve.com/console/docs Reve API Documentation
+        def create(prompt:, references: nil, aspect_ratio: nil, postprocessing: nil,
+                   test_time_scaling: nil, version: nil, accept: nil, breadcrumb: nil)
+          validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH)
+          validate_references!(references)
+          validate_aspect_ratio!(aspect_ratio, Configuration::ASPECT_RATIOS)
+          validate_postprocessing!(postprocessing)
+          validate_test_time_scaling!(test_time_scaling)
+
+          body = build_create_body(prompt: prompt, references: references, aspect_ratio: aspect_ratio,
+                                   postprocessing: postprocessing, test_time_scaling: test_time_scaling,
+                                   version: version)
+          params = breadcrumb ? { breadcrumb: breadcrumb } : nil
+
+          response = post(CREATE_ENDPOINT, body, params: params, accept: accept)
+          ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
+        end
+
+        private
+
+        # Builds the request body for the create endpoint.
+        #
+        # @return [Hash] Request body with only the provided options
+        # @api private
+        def build_create_body(prompt:, references:, aspect_ratio:, postprocessing:, test_time_scaling:, version:)
+          body = { prompt: prompt }
+          body[:references] = references if references
+          body[:aspect_ratio] = aspect_ratio if aspect_ratio
+          body[:postprocessing] = postprocessing if postprocessing
+          body[:test_time_scaling] = test_time_scaling if test_time_scaling
+          body[:version] = version if version
+          body
+        end
+
+        # Validates the references array.
+        #
+        # @param references [Array<Hash>, nil] Reference image entries
+        # @raise [ValidationError] if not an Array, exceeds the maximum, or
+        #   contains a malformed entry
+        # @api private
+        def validate_references!(references)
+          return if references.nil?
+
+          unless references.is_a?(Array)
+            raise ValidationError, "References must be an Array of Hashes with exactly one of 'data' or 'ref'"
+          end
+
+          max = Configuration::V2_MAX_REFERENCES
+          raise ValidationError, "Maximum #{max} references allowed" if references.length > max
+
+          references.each_with_index { |reference, index| validate_reference!(reference, index) }
+        end
+
+        # Validates a single reference entry.
+        #
+        # @param reference [Hash] Reference entry with exactly one of +data+ or +ref+
+        # @param index [Integer] Position in the references array (for error messages)
+        # @raise [ValidationError] if the entry is not a Hash, has both or
+        #   neither of +data+/+ref+, or has a non-String value
+        # @api private
+        def validate_reference!(reference, index)
+          unless reference.is_a?(Hash)
+            raise ValidationError, "Reference at index #{index} must be a Hash with exactly one of 'data' or 'ref'"
+          end
+
+          data = reference[:data] || reference["data"]
+          ref = reference[:ref] || reference["ref"]
+
+          if data.nil? == ref.nil?
+            raise ValidationError, "Reference at index #{index} must include exactly one of 'data' or 'ref'"
+          end
+
+          if data.nil?
+            validate_reference_value!(ref, "ref", index)
+          else
+            validate_reference_value!(data, "data", index)
+          end
+        end
+
+        # Validates a reference +data+ or +ref+ value.
+        #
+        # @param value [Object] The data or ref value
+        # @param key [String] Which key the value came from ("data" or "ref")
+        # @param index [Integer] Position in the references array
+        # @raise [ValidationError] if value is not a non-empty String
+        # @api private
+        def validate_reference_value!(value, key, index)
+          return if value.is_a?(String) && !value.empty?
+
+          raise ValidationError, "Reference at index #{index} '#{key}' must be a non-empty String"
+        end
+      end
+    end
+  end
+end