runapi-imagen-4 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5f4e885df581cc7e939d349397a8948723856802af80d74a7f90929438d733f
-  data.tar.gz: 000d78ebd2300190d80fdc136d85f30c74ee6f3f69485b71ded0398c85646063
+  metadata.gz: 0bbf9045af4c340dcafd79540eb6ad94787e442eca639d8d274553212b94fe4b
+  data.tar.gz: 3dbfbfe5bb5b55cc79425a7c453299cb293805d0069e506dc31062811329fdb6
 SHA512:
-  metadata.gz: e4b433e9dab6777d83566a7a86cd7c486a7c69912bd6b1e8cb1c5eb3cf1a2e6082c7a6f6394c308b457f501a669977fdde102cc32a566a3815586ec1efe88e99
-  data.tar.gz: 47b962cddc2b01bbcb27736c19e7c72af79def1b83193e318d79081b241c51485a56489547f4b97717c361b606dc86027c437cdcdefa0b8bc3973736907ec6d7
+  metadata.gz: a88bfe60addfcf7ff41e0dba18c93b3809c57330d837c2dacc5ca1e630edc770cfcddf7ae818632fa13f4c206426824104d1d735740a6a94bb9a9491a9069a74
+  data.tar.gz: 600070f645056e36fa40caafcfb165e746ff69a572dcb4da4c9fb5d91bdd801f4cdcc77fff0668968cd01e902f3515f7020cb34ccb9c77d67b128efea0771dde

data/README.md

@@ -0,0 +1,45 @@
+# Imagen API Ruby SDK for RunAPI
+
+The imagen api Ruby SDK is the language-specific package for Imagen 4 on RunAPI. Use this imagen api package for text-to-image, image editing, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+
+This imagen api README is the Ruby package guide inside the public `imagen4-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/imagen-4; for API reference, use https://runapi.ai/docs#imagen-4; for SDK docs, use https://runapi.ai/docs#sdk-imagen-4.
+
+## Install
+
+```bash
+gem install runapi-imagen4
+```
+
+## Quick start
+
+```ruby
+require "runapi-imagen4"
+
+client = RunApi::Imagen4::Client.new
+task = client.generations.create(
+  # Pass the Imagen 4 JSON request body from https://runapi.ai/docs#imagen-4.
+)
+status = client.generations.get(task.id)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion. In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.
+
+## Language notes
+
+Use Ruby keyword arguments and the `RunApi::Imagen4` error classes when building image jobs, Rails workers, or scripts. The available resources include generations. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/imagen-4
+- SDK docs: https://runapi.ai/docs#sdk-imagen-4
+- Product docs: https://runapi.ai/docs#imagen-4
+- Pricing and rate limits: https://runapi.ai/models/imagen-4/imagen-4
+- Provider comparison: https://runapi.ai/providers/google
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/imagen4-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/imagen_4/client.rb

@@ -2,14 +2,26 @@
 
 module RunApi
   module Imagen4
-    class Client
+    # Imagen 4 text-to-image and remix API client.
+    #
+    # Three text-to-image quality tiers (imagen-4, imagen-4-fast, imagen-4-ultra)
+    # and a dedicated remix model for guided image transformation.
+    #
+    # @example
+    #   client = RunApi::Imagen4::Client.new(api_key: "your-api-key")
+    #   result = client.text_to_image.run(
+    #     model: "imagen-4", prompt: "A photorealistic mountain landscape"
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToImage] Text-to-image generation across quality tiers.
       attr_reader :text_to_image
+      # @return [Resources::RemixImage] Remix existing images with text-guided transformations.
+      attr_reader :remix_image
 
       def initialize(api_key: nil, **options)
-        @api_key = Core::Auth.resolve_api_key(api_key)
-        client_options = Core::ClientOptions.new(api_key: @api_key, **options)
-        http = client_options.http_client || Core::HttpClient.new(client_options)
+        super
         @text_to_image = Resources::TextToImage.new(http)
+        @remix_image = Resources::RemixImage.new(http)
       end
     end
   end

data/lib/runapi/imagen_4/resources/remix_image.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Imagen4
+    module Resources
+      # Imagen 4 image remix resource.
+      # Transform source images guided by a text prompt (up to 8 source images).
+      class RemixImage
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/imagen_4/remix_image"
+        RESPONSE_CLASS = Types::RemixImageResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedRemixImageResponse
+        SOURCE_IMAGE_URLS_MAX = 8
+
+        def initialize(http)
+          @http = http
+        end
+
+        def run(**params)
+          task = create(**params)
+          poll_until_complete { get(task.id) }
+        end
+
+        def create(**params)
+          params = compact_params(params)
+          validate_params!(params)
+          request(:post, ENDPOINT, body: params)
+        end
+
+        def get(id)
+          request(:get, "#{ENDPOINT}/#{id}")
+        end
+
+        private
+
+        def validate_params!(params)
+          model = param(params, :model)
+          raise Core::ValidationError, "model is required" unless model
+          unless Types::REMIX_MODELS.include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::REMIX_MODELS.join(", ")}"
+          end
+          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
+
+          validate_source_image_urls!(params)
+          validate_optional!(params, :aspect_ratio, Types::PRO_ASPECT_RATIOS)
+          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
+          validate_optional!(params, :output_format, Types::OUTPUT_FORMATS)
+        end
+
+        def validate_source_image_urls!(params)
+          urls = param(params, :source_image_urls)
+          raise Core::ValidationError, "source_image_urls is required" if urls.nil? || (urls.respond_to?(:empty?) && urls.empty?)
+          return unless urls.respond_to?(:size) && urls.size > SOURCE_IMAGE_URLS_MAX
+
+          raise Core::ValidationError, "source_image_urls supports up to #{SOURCE_IMAGE_URLS_MAX} images"
+        end
+      end
+    end
+  end
+end

data/lib/runapi/imagen_4/resources/text_to_image.rb

@@ -3,14 +3,14 @@
 module RunApi
   module Imagen4
     module Resources
+      # Imagen 4 text-to-image generation resource.
+      # Generate images from text with three quality tiers; imagen-4-fast supports batch output.
       class TextToImage
         include RunApi::Core::ResourceHelpers
 
         ENDPOINT = "/api/v1/imagen_4/text_to_image"
         RESPONSE_CLASS = Types::TextToImageResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTextToImageResponse
-        TEXT_ONLY_FIELDS = %i[negative_prompt seed num_images].freeze
-        PRO_ONLY_FIELDS = %i[image_input resolution output_format].freeze
 
         def initialize(http)
           @http = http
@@ -40,35 +40,15 @@ module RunApi
           model = param(params, :model)
           raise Core::ValidationError, "Invalid model: #{model}. Must be: #{Types::MODELS.join(", ")}" unless Types::MODELS.include?(model)
 
-          text_model?(model) ? validate_text_params!(params, model) : validate_pro_params!(params, model)
+          validate_text_params!(params, model)
         end
 
         def validate_text_params!(params, model)
-          reject_present!(params, PRO_ONLY_FIELDS, model)
           validate_optional!(params, :aspect_ratio, Types::TEXT_ASPECT_RATIOS)
-          return unless param(params, :num_images)
+          return unless param(params, :output_count)
 
-          raise Core::ValidationError, "num_images is only supported for imagen-4-fast" unless model == "imagen-4-fast"
-          validate_optional!(params, :num_images, Types::NUM_IMAGES)
-        end
-
-        def validate_pro_params!(params, model)
-          reject_present!(params, TEXT_ONLY_FIELDS, model)
-          validate_optional!(params, :aspect_ratio, Types::PRO_ASPECT_RATIOS)
-          validate_optional!(params, :resolution, Types::RESOLUTIONS)
-          validate_optional!(params, :output_format, Types::OUTPUT_FORMATS)
-          return unless param(params, :image_input)&.size.to_i > 8
-
-          raise Core::ValidationError, "image_input supports up to 8 images"
-        end
-
-        def reject_present!(params, fields, model)
-          invalid = fields.find { |field| param(params, field) }
-          raise Core::ValidationError, "#{invalid} is not supported for #{model}" if invalid
-        end
-
-        def text_model?(model)
-          Types::TEXT_MODELS.include?(model)
+          raise Core::ValidationError, "output_count is only supported for imagen-4-fast" unless model == "imagen-4-fast"
+          validate_optional!(params, :output_count, Types::OUTPUT_COUNTS)
         end
       end
     end

data/lib/runapi/imagen_4/types.rb

@@ -2,24 +2,42 @@
 
 module RunApi
   module Imagen4
+    # Imagen 4 type constants and response models.
+    # Text-to-image supports three quality tiers; remix accepts source images
+    # with extended aspect ratios, resolution, and format control.
     module Types
       TEXT_MODELS = %w[imagen-4 imagen-4-fast imagen-4-ultra].freeze
-      MODELS = (TEXT_MODELS + %w[imagen-4-pro-image-to-image]).freeze
+      REMIX_MODELS = %w[imagen-4-pro-remix-image].freeze
+      MODELS = (TEXT_MODELS + REMIX_MODELS).freeze
       TEXT_ASPECT_RATIOS = %w[1:1 16:9 9:16 3:4 4:3].freeze
+      # Extended aspect ratios for remix, including "auto" which infers from source images.
       PRO_ASPECT_RATIOS = %w[1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 auto].freeze
-      RESOLUTIONS = %w[1K 2K 4K].freeze
+      OUTPUT_RESOLUTIONS = %w[1k 2k 4k].freeze
       OUTPUT_FORMATS = %w[png jpg].freeze
-      NUM_IMAGES = %w[1 2 3 4].freeze
+      # Batch sizes for imagen-4-fast (the only model supporting multi-image output).
+      OUTPUT_COUNTS = [1, 2, 3, 4].freeze
+
+      # A generated image with its CDN URL and optional unprocessed origin URL.
+      class Image < RunApi::Core::BaseModel
+        optional :url, String
+        optional :origin_url, String
+      end
 
       class TextToImageResponse < RunApi::Core::TaskResponse
         required :id, String
         optional :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
-        optional :result_urls, [ String ]
+        optional :images, [-> { Image }]
         optional :error, String
       end
 
       class CompletedTextToImageResponse < TextToImageResponse
-        required :result_urls, [ String ]
+        required :images, [-> { Image }]
+      end
+
+      class RemixImageResponse < TextToImageResponse
+      end
+
+      class CompletedRemixImageResponse < CompletedTextToImageResponse
       end
     end
   end

data/lib/runapi/imagen_4.rb

@@ -3,4 +3,5 @@
 require "runapi/core"
 require_relative "imagen_4/types"
 require_relative "imagen_4/resources/text_to_image"
+require_relative "imagen_4/resources/remix_image"
 require_relative "imagen_4/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-imagen-4
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - RunAPI
@@ -15,25 +15,31 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.4
-description: RunAPI Imagen 4 SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: The imagen api Ruby SDK is the language-specific package for Imagen 4
+  on RunAPI. Use this imagen api package for text-to-image, image editing, and creative
+  production flows when your application needs JSON request bodies, task status lookup,
+  and consistent RunAPI errors in Ruby.
 email:
 - contact@runapi.ai
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
+- README.md
 - lib/runapi-imagen_4.rb
 - lib/runapi/imagen_4.rb
 - lib/runapi/imagen_4/client.rb
+- lib/runapi/imagen_4/resources/remix_image.rb
 - lib/runapi/imagen_4/resources/text_to_image.rb
 - lib/runapi/imagen_4/types.rb
 homepage: https://runapi.ai/models/imagen-4
@@ -41,7 +47,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/imagen-4
-  documentation_uri: https://github.com/runapi-ai/imagen-4-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/imagen-4-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/imagen-4-sdk
   changelog_uri: https://github.com/runapi-ai/imagen-4-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -60,5 +66,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Imagen 4 API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Imagen API Ruby SDK for RunAPI
 test_files: []