runapi-ideogram-v3 0.2.4 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa5a4f6c6c74bfc6cdaa9bf20a9ee5e32e5d29767cc55fe832176dd39fcc941c
-  data.tar.gz: adeccc0f2be866d773397005f46603736545f864d4a8a8e16c72e3c06bce0ea1
+  metadata.gz: dde03331810a873fb90e94add731e8b5ba2fb708b65793635ba116c62da37097
+  data.tar.gz: 30b5662428e00828dbe82f6a86c3d606cd250a1146bc2587bf634bda637985dd
 SHA512:
-  metadata.gz: b694267f9dab0786be2f1aa5dbc365aaa4b174bd320356f8f456dd7b7acd8e06ddd24dc1021547945da86e74a2148112797a55762e208379cc2a16b44887674f
-  data.tar.gz: 02704e5b9736501d2a8ef2d55447d947643843407c1e75f565e7f085cb2388956d00368c33cb3aa98c7af778c17597571bffd6b6be22d52294fb0c9092e635f7
+  metadata.gz: 844c94f0cc39f4f591ea2cef59d31f7db91b0a33e0901df371e027b3bb14e80ff12cacb73c295b039894a3236b6f047fee0d9ce6fa7b046b590c6502246677c9
+  data.tar.gz: 32848ec85bbdc5d9b57e2e45215260a0652a40053a9d7584061d6aeebabaa8ebc46cf96f831bfd55d7513d9a90b6ed22479e6c0c5842f1948cdb81f6e96db771

data/README.md

@@ -0,0 +1,46 @@
+# Ideogram API Ruby SDK for RunAPI
+
+The ideogram api Ruby SDK is the language-specific package for Ideogram V3 on RunAPI. Use this ideogram api package for text-to-image, character reference generation, edit, remix, reframe, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+
+This ideogram api README is the Ruby package guide inside the public `ideogram-v3-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/ideogram-v3; for API reference, use https://runapi.ai/docs#ideogram-v3; for SDK docs, use https://runapi.ai/docs#sdk-ideogram-v3.
+
+## Install
+
+```bash
+gem install runapi-ideogram-v3
+```
+
+## Quick start
+
+```ruby
+require "runapi-ideogram-v3"
+
+client = RunApi::IdeogramV3::Client.new
+task = client.text_to_image.create(
+  model: "ideogram-v3-text-to-image",
+  prompt: "A cinematic lakeside at twilight with neon reeds"
+)
+status = client.text_to_image.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::IdeogramV3` error classes when building image jobs, Rails workers, or scripts. The available resources are `text_to_image`, `edit_image`, `remix_image`, and `reframe_image`. 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/ideogram-v3
+- SDK docs: https://runapi.ai/docs#sdk-ideogram-v3
+- Product docs: https://runapi.ai/docs#ideogram-v3
+- Pricing and rate limits: https://runapi.ai/models/ideogram-v3/text-to-image
+- Provider comparison: https://runapi.ai/providers/ideogram
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/ideogram-v3-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/ideogram_v3/client.rb

@@ -4,26 +4,31 @@ module RunApi
   module IdeogramV3
     # Ideogram V3 image generation API client.
     #
+    # Supports text-to-image, inpaint editing, remix, and reframe operations.
+    # Character model variants add character consistency from reference images.
+    #
     # @example
     #   client = RunApi::IdeogramV3::Client.new(api_key: "your-api-key")
     #   result = client.text_to_image.run(
     #     model: "ideogram-v3-text-to-image",
     #     prompt: "A cinematic lakeside at twilight"
     #   )
-    class Client
-      # @return [Resources::TextToImage] Text-to-image operations.
-      # @return [Resources::EditImage] Inpaint-with-mask operations.
-      # @return [Resources::RemixImage] Image remix operations.
-      attr_reader :text_to_image, :edit_image, :remix_image
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToImage] Text-to-image generation operations.
+      attr_reader :text_to_image
+      # @return [Resources::EditImage] Inpaint-with-mask editing operations.
+      attr_reader :edit_image
+      # @return [Resources::RemixImage] Prompt-guided image variation operations.
+      attr_reader :remix_image
+      # @return [Resources::ReframeImage] Aspect ratio reframing operations.
+      attr_reader :reframe_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)
         @edit_image = Resources::EditImage.new(http)
         @remix_image = Resources::RemixImage.new(http)
+        @reframe_image = Resources::ReframeImage.new(http)
       end
     end
   end

data/lib/runapi/ideogram_v3/resources/edit_image.rb

@@ -3,7 +3,7 @@
 module RunApi
   module IdeogramV3
     module Resources
-      # Inpaint with mask (model: ideogram-v3-edit).
+      # Inpaint editing using a mask to define the regenerated region.
       class EditImage
         include RunApi::Core::ResourceHelpers
 
@@ -36,8 +36,8 @@ module RunApi
         def validate_params!(params)
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless model
-          unless model == Types::EDIT_MODEL
-            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::EDIT_MODEL}"
+          unless [Types::EDIT_MODEL, Types::CHARACTER_EDIT_MODEL].include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::EDIT_MODEL} or #{Types::CHARACTER_EDIT_MODEL}"
           end
 
           prompt = param(params, :prompt)
@@ -46,10 +46,29 @@ module RunApi
             raise Core::ValidationError, "prompt must be at most #{PROMPT_MAX_LENGTH} characters"
           end
 
-          raise Core::ValidationError, "image_url is required" unless param(params, :image_url)
+          raise Core::ValidationError, "source_image_url is required" unless param(params, :source_image_url)
           raise Core::ValidationError, "mask_url is required" unless param(params, :mask_url)
 
           validate_optional!(params, :rendering_speed, Types::RENDERING_SPEEDS)
+          validate_character_fields!(params, model)
+        end
+
+        def validate_character_fields!(params, model)
+          refs = param(params, :reference_image_urls)
+          if model == Types::CHARACTER_EDIT_MODEL
+            raise Core::ValidationError, "reference_image_urls is required" unless refs.is_a?(Array) && refs.any?
+            validate_optional!(params, :style, Types::CHARACTER_STYLES)
+          elsif refs || param(params, :style)
+            raise Core::ValidationError, "character edit fields are not supported for #{model}"
+          end
+          validate_output_count!(params)
+        end
+
+        def validate_output_count!(params)
+          return unless (output_count = param(params, :output_count))
+          return if Types::OUTPUT_COUNTS.include?(output_count)
+
+          raise Core::ValidationError, "Invalid output_count: #{output_count}. Must be one of: #{Types::OUTPUT_COUNTS.join(", ")}"
         end
       end
     end

data/lib/runapi/ideogram_v3/resources/reframe_image.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RunApi
+  module IdeogramV3
+    module Resources
+      # Extends or crops an image to a new aspect ratio without regenerating content.
+      class ReframeImage
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/ideogram_v3/reframe_image"
+        RESPONSE_CLASS = Types::IdeogramResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedIdeogramResponse
+
+        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 model == Types::REFRAME_MODEL
+            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::REFRAME_MODEL}"
+          end
+
+          raise Core::ValidationError, "source_image_url is required" unless param(params, :source_image_url)
+          raise Core::ValidationError, "aspect_ratio is required" unless param(params, :aspect_ratio)
+
+          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+          validate_optional!(params, :rendering_speed, Types::RENDERING_SPEEDS)
+          validate_optional!(params, :style, Types::STYLES)
+          validate_output_count!(params)
+        end
+
+        def validate_output_count!(params)
+          return unless (output_count = param(params, :output_count))
+          return if Types::OUTPUT_COUNTS.include?(output_count)
+
+          raise Core::ValidationError, "Invalid output_count: #{output_count}. Must be one of: #{Types::OUTPUT_COUNTS.join(", ")}"
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module RunApi
   module IdeogramV3
     module Resources
-      # Image remix (model: ideogram-v3-remix).
+      # Creates a variation of a source image guided by a new text prompt.
       class RemixImage
         include RunApi::Core::ResourceHelpers
 
@@ -12,6 +12,7 @@ module RunApi
         COMPLETED_RESPONSE_CLASS = Types::CompletedIdeogramResponse
         PROMPT_MAX_LENGTH = 5000
         STRENGTH_MIN = 0.01
+        CHARACTER_REMIX_STRENGTH_MIN = 0.1
         STRENGTH_MAX = 1.0
 
         def initialize(http)
@@ -38,8 +39,8 @@ module RunApi
         def validate_params!(params)
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless model
-          unless model == Types::REMIX_MODEL
-            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::REMIX_MODEL}"
+          unless [Types::REMIX_MODEL, Types::CHARACTER_REMIX_MODEL].include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::REMIX_MODEL} or #{Types::CHARACTER_REMIX_MODEL}"
           end
 
           prompt = param(params, :prompt)
@@ -48,25 +49,37 @@ module RunApi
             raise Core::ValidationError, "prompt must be at most #{PROMPT_MAX_LENGTH} characters"
           end
 
-          raise Core::ValidationError, "image_url is required" unless param(params, :image_url)
+          raise Core::ValidationError, "source_image_url is required" unless param(params, :source_image_url)
 
           validate_optional!(params, :rendering_speed, Types::RENDERING_SPEEDS)
-          validate_optional!(params, :style, Types::STYLES)
-          validate_optional!(params, :image_size, Types::IMAGE_SIZES)
+          style_values = (model == Types::CHARACTER_REMIX_MODEL) ? Types::CHARACTER_STYLES : Types::STYLES
+          validate_optional!(params, :style, style_values)
+          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+          validate_character_fields!(params, model)
 
-          if (num_images = param(params, :num_images))
-            unless Types::NUM_IMAGES.include?(num_images.to_s)
-              raise Core::ValidationError, "Invalid num_images: #{num_images}. Must be one of: #{Types::NUM_IMAGES.join(", ")}"
+          if (output_count = param(params, :output_count))
+            unless Types::OUTPUT_COUNTS.include?(output_count)
+              raise Core::ValidationError, "Invalid output_count: #{output_count}. Must be one of: #{Types::OUTPUT_COUNTS.join(", ")}"
             end
           end
 
           if (strength = param(params, :strength))
             numeric = Float(strength, exception: false)
-            if numeric.nil? || numeric < STRENGTH_MIN || numeric > STRENGTH_MAX
-              raise Core::ValidationError, "strength must be between #{STRENGTH_MIN} and #{STRENGTH_MAX}"
+            min = (model == Types::CHARACTER_REMIX_MODEL) ? CHARACTER_REMIX_STRENGTH_MIN : STRENGTH_MIN
+            if numeric.nil? || numeric < min || numeric > STRENGTH_MAX
+              raise Core::ValidationError, "strength must be between #{min} and #{STRENGTH_MAX}"
             end
           end
         end
+
+        def validate_character_fields!(params, model)
+          refs = param(params, :reference_image_urls)
+          if model == Types::CHARACTER_REMIX_MODEL
+            raise Core::ValidationError, "reference_image_urls is required" unless refs.is_a?(Array) && refs.any?
+          elsif refs || param(params, :style_reference_image_urls) || param(params, :reference_mask_urls)
+            raise Core::ValidationError, "character remix fields are not supported for #{model}"
+          end
+        end
       end
     end
   end

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

@@ -3,7 +3,7 @@
 module RunApi
   module IdeogramV3
     module Resources
-      # Text-to-image generation (model: ideogram-v3-text-to-image).
+      # Generates images from text with configurable speed, style, and aspect ratio.
       class TextToImage
         include RunApi::Core::ResourceHelpers
 
@@ -36,8 +36,8 @@ module RunApi
         def validate_params!(params)
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless model
-          unless model == Types::GENERATION_MODEL
-            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::GENERATION_MODEL}"
+          unless [Types::GENERATION_MODEL, Types::CHARACTER_MODEL].include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be #{Types::GENERATION_MODEL} or #{Types::CHARACTER_MODEL}"
           end
 
           prompt = param(params, :prompt)
@@ -47,8 +47,28 @@ module RunApi
           end
 
           validate_optional!(params, :rendering_speed, Types::RENDERING_SPEEDS)
-          validate_optional!(params, :style, Types::STYLES)
-          validate_optional!(params, :image_size, Types::IMAGE_SIZES)
+          style_values = (model == Types::CHARACTER_MODEL) ? Types::CHARACTER_STYLES : Types::STYLES
+          validate_optional!(params, :style, style_values)
+          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+          validate_character_refs!(params, model)
+          validate_output_count!(params)
+        end
+
+        def validate_character_refs!(params, model)
+          refs = param(params, :reference_image_urls)
+          if model == Types::CHARACTER_MODEL
+            raise Core::ValidationError, "reference_image_urls is required" unless refs.is_a?(Array) && refs.any?
+          elsif refs
+            raise Core::ValidationError, "reference_image_urls is not supported for #{model}"
+          end
+        end
+
+        def validate_output_count!(params)
+          output_count = param(params, :output_count)
+          return unless output_count
+          return if Types::OUTPUT_COUNTS.include?(output_count)
+
+          raise Core::ValidationError, "Invalid output_count: #{output_count}. Must be one of: #{Types::OUTPUT_COUNTS.join(", ")}"
         end
       end
     end

data/lib/runapi/ideogram_v3/types.rb

@@ -2,32 +2,44 @@
 
 module RunApi
   module IdeogramV3
+    # Type definitions and constants for Ideogram V3.
+    # Character model variants add character consistency from reference images.
     module Types
       GENERATION_MODEL = "ideogram-v3-text-to-image"
       EDIT_MODEL = "ideogram-v3-edit"
       REMIX_MODEL = "ideogram-v3-remix"
+      CHARACTER_MODEL = "ideogram-v3-character"
+      CHARACTER_EDIT_MODEL = "ideogram-v3-character-edit"
+      CHARACTER_REMIX_MODEL = "ideogram-v3-character-remix"
+      REFRAME_MODEL = "ideogram-v3-reframe"
 
-      RENDERING_SPEEDS = %w[TURBO BALANCED QUALITY].freeze
-      STYLES = %w[AUTO GENERAL REALISTIC DESIGN].freeze
-      IMAGE_SIZES = %w[
-        square square_hd portrait_4_3 portrait_16_9 landscape_4_3 landscape_16_9
-      ].freeze
-      NUM_IMAGES = %w[1 2 3 4].freeze
+      # Speed-quality tradeoff: turbo is fastest, quality is highest fidelity.
+      RENDERING_SPEEDS = %w[turbo balanced quality].freeze
+      # Visual style presets for standard (non-character) models.
+      STYLES = %w[auto general realistic design].freeze
+      # Visual style presets for character-consistency models.
+      CHARACTER_STYLES = %w[auto realistic fiction].freeze
+      ASPECT_RATIOS = %w[1:1 3:4 9:16 4:3 16:9].freeze
+      # Number of images per request (1-4).
+      OUTPUT_COUNTS = [1, 2, 3, 4].freeze
 
+      # A single generated image with its CDN URL.
       class Image < RunApi::Core::BaseModel
         optional :url, String
       end
 
+      # Normalized response for all Ideogram V3 endpoints.
+      # +images+ is populated once +status+ is +"completed"+.
       class IdeogramResponse < RunApi::Core::TaskResponse
         required :id, String
         optional :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
-        optional :images, [ -> { Image } ]
+        optional :images, [-> { Image }]
         optional :error, String
       end
 
       # Narrowed response returned by `run()` once polling sees `status: "completed"`.
       class CompletedIdeogramResponse < IdeogramResponse
-        required :images, [ -> { Image } ]
+        required :images, [-> { Image }]
       end
     end
   end

data/lib/runapi/ideogram_v3.rb

@@ -5,6 +5,7 @@ require_relative "ideogram_v3/types"
 require_relative "ideogram_v3/resources/text_to_image"
 require_relative "ideogram_v3/resources/edit_image"
 require_relative "ideogram_v3/resources/remix_image"
+require_relative "ideogram_v3/resources/reframe_image"
 require_relative "ideogram_v3/client"
 
 module RunApi

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-ideogram-v3
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,26 +15,32 @@ 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 Ideogram V3 SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: The ideogram api Ruby SDK is the language-specific package for Ideogram
+  V3 on RunAPI. Use this ideogram api package for text-to-image, character reference
+  generation, edit, remix, reframe, 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-ideogram_v3.rb
 - lib/runapi/ideogram_v3.rb
 - lib/runapi/ideogram_v3/client.rb
 - lib/runapi/ideogram_v3/resources/edit_image.rb
+- lib/runapi/ideogram_v3/resources/reframe_image.rb
 - lib/runapi/ideogram_v3/resources/remix_image.rb
 - lib/runapi/ideogram_v3/resources/text_to_image.rb
 - lib/runapi/ideogram_v3/types.rb
@@ -43,7 +49,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/ideogram-v3
-  documentation_uri: https://github.com/runapi-ai/ideogram-v3-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/ideogram-v3-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/ideogram-v3-sdk
   changelog_uri: https://github.com/runapi-ai/ideogram-v3-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -62,5 +68,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Ideogram V3 API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Ideogram API Ruby SDK for RunAPI
 test_files: []