runapi-ideogram-v3 0.2.3 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b99744e9c8dfaa76dad7181523350b22871f82471cdb615d7ba20400edf955
-  data.tar.gz: adeccc0f2be866d773397005f46603736545f864d4a8a8e16c72e3c06bce0ea1
+  metadata.gz: fc1b721eb9666ebffa9d974a30ffb4f015b4d69ca74ead610686c17b6b0bcff2
+  data.tar.gz: 786042996e23818cdb4bc76eb869812176acd99415210cff8ddd68bdb16bea17
 SHA512:
-  metadata.gz: 6f97dd9a1b88f82dae21ec42d7787caa5de508d6d5f4e99b3130a096aa25a062220c2836e1143af9faa83447dcbc3e14d4c3a72b2868718dc9889ef8c7f2d1df
-  data.tar.gz: 02704e5b9736501d2a8ef2d55447d947643843407c1e75f565e7f085cb2388956d00368c33cb3aa98c7af778c17597571bffd6b6be22d52294fb0c9092e635f7
+  metadata.gz: 8f266081742ba4681706682f442ede15030f87414320db93931a0ecf01bc4c93de779b8bbdf373bd82c0c9a5476aade094f3e53c53bd20c2c606f37974a64496
+  data.tar.gz: 67f3908f740aea4409b719a265b019d5da5fdd538ff5e2ddd4b02173ec5b7c01b22c452ead216da9f663c1717996a9b381696d3447e8fff8b0e1d87f08c8d1cc

data/README.md

@@ -0,0 +1,44 @@
+# 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.
+
+## 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

@@ -14,7 +14,8 @@ module RunApi
       # @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
+      # @return [Resources::ReframeImage] Image reframe operations.
+      attr_reader :text_to_image, :edit_image, :remix_image, :reframe_image
 
       def initialize(api_key: nil, **options)
         @api_key = Core::Auth.resolve_api_key(api_key)
@@ -24,6 +25,7 @@ module RunApi
         @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

@@ -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
+      # Reframe an input image (model: ideogram-v3-reframe).
+      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

@@ -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

@@ -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

@@ -6,13 +6,16 @@ module RunApi
       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
+      RENDERING_SPEEDS = %w[turbo balanced quality].freeze
+      STYLES = %w[auto general realistic design].freeze
+      CHARACTER_STYLES = %w[auto realistic fiction].freeze
+      ASPECT_RATIOS = %w[1:1 3:4 9:16 4:3 16:9].freeze
+      OUTPUT_COUNTS = [1, 2, 3, 4].freeze
 
       class Image < RunApi::Core::BaseModel
         optional :url, String
@@ -21,13 +24,13 @@ module RunApi
       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.3
+  version: 0.2.6
 platform: ruby
 authors:
 - RunAPI
@@ -15,26 +15,32 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 0.2.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.3
-description: RunAPI Ideogram V3 SDK for JavaScript, Ruby, and Go
+        version: 0.2.5
+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://runapi.ai/models/ideogram-v3
+  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: []