runapi-seedream 0.2.4 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ab6f0090893fffc1225a5772b6f43b64be31b432f5c6c49827fc746051b371
-  data.tar.gz: b486a1e417fc2a6c7cfed7f90b1ddf4391acb6d04e436ed21292c7de5a20797e
+  metadata.gz: d8ca9b02c90b624e837c7652223020526592784b12d0f0a6f54f7afc6d9ed4d7
+  data.tar.gz: a7b2b5fe72b6135055d4f0838fd9e704f6222c9cd1410615d6b1ca718af078c2
 SHA512:
-  metadata.gz: 35440b09308862129346ac31a2902c7870070ba8232b0bda93d6df730d5828da666d9c1f9443bf2029a67eb60589848f7f6fdd895edbc33882633fb0d20c3635
-  data.tar.gz: 67ff779b1d23ee0ec88a441910330c98912f029ff4b286f35ffcb1a428661dac1b3a2951f1d5c18cbeaaa8f0487db9b9adce76cf69e130166bfdbf844b55db83
+  metadata.gz: f4a3270d5d1920a9151e5d9053aba445e7a07125522e4508a5da35585d9fc69ecbed5681607fe5895bd829ef50b79b8fb16021dfcb7c76174a8e14e5c090cf28
+  data.tar.gz: 2f5cfa1042a0b46d66c70586cd95b24e688eac376699708a8806c8c78bc1ee9aa5abce75eb98f5ef32bbc73985aadad9b99ebead702603dbfef2a2d64cbd60a6

data/README.md

@@ -0,0 +1,48 @@
+# Seedream API Ruby SDK for RunAPI
+
+The seedream api Ruby SDK is the language-specific package for Seedream on RunAPI. Use this seedream 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 seedream api README is the Ruby package guide inside the public `seedream-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/seedream; for API reference, use https://runapi.ai/docs#seedream; for SDK docs, use https://runapi.ai/docs#sdk-seedream.
+
+## Install
+
+```bash
+gem install runapi-seedream
+```
+
+## Quick start
+
+```ruby
+require "runapi-seedream"
+
+client = RunApi::Seedream::Client.new
+task = client.text_to_image.create(
+  model: "seedream-v4-text-to-image",
+  prompt: "A precise product render of a glass teapot on white marble",
+  aspect_ratio: "16:9",
+  output_resolution: "2k",
+  output_count: 3
+)
+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::Seedream` error classes when building image jobs, Rails workers, or scripts. The package exposes `text_to_image` for text models and `edit_image` for editing models. 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/seedream
+- SDK docs: https://runapi.ai/docs#sdk-seedream
+- Product docs: https://runapi.ai/docs#seedream
+- Pricing and rate limits: https://runapi.ai/models/seedream/v4-text-to-image
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/seedream-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/seedream/client.rb

@@ -2,15 +2,38 @@
 
 module RunApi
   module Seedream
-    class Client
+    # Seedream image generation and editing API client.
+    #
+    # Three model families with different field requirements:
+    # - 4.5: requires aspect_ratio and output_quality
+    # - 5-lite: same required fields as 4.5, faster generation
+    # - V4: uses output_resolution instead; supports seed and batch output_count
+    #
+    # @example
+    #   client = RunApi::Seedream::Client.new(api_key: "your-api-key")
+    #
+    #   # Seedream 4.5
+    #   result = client.text_to_image.run(
+    #     model: "seedream-4.5-text-to-image",
+    #     prompt: "A beautiful product render",
+    #     aspect_ratio: "16:9", output_quality: "high"
+    #   )
+    #
+    #   # Seedream V4 with batch output
+    #   batch = client.text_to_image.run(
+    #     model: "seedream-v4-text-to-image",
+    #     prompt: "Minimalist logo design", output_count: 4
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToImage] Text-to-image generation across model versions.
       attr_reader :text_to_image
+      # @return [Resources::EditImage] Edit source images with a text prompt.
+      attr_reader :edit_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)
       end
     end
   end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Seedream
+    module Resources
+      # Seedream image editing resource.
+      # Modifies source images according to a text prompt.
+      # V4 models accept up to 10 source images; 4.5 and 5-lite accept up to 14.
+      class EditImage
+        include RunApi::Core::ResourceHelpers
+
+        ENDPOINT = "/api/v1/seedream/edit_image"
+        RESPONSE_CLASS = Types::EditImageResponse
+        COMPLETED_RESPONSE_CLASS = Types::CompletedEditImageResponse
+        PROMPT_MAX_LENGTH = 3000
+        V4_PROMPT_MAX_LENGTH = 5000
+        PROMPT_MIN_LENGTH_LITE = 3
+        V4_OUTPUT_COUNT_RANGE = (1..6)
+
+        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::EDIT_MODELS.include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::EDIT_MODELS.join(", ")}"
+          end
+
+          prompt = param(params, :prompt)
+          raise Core::ValidationError, "prompt is required" unless prompt.is_a?(String) && !prompt.empty?
+          max_length = Types::V4_MODELS.include?(model) ? V4_PROMPT_MAX_LENGTH : PROMPT_MAX_LENGTH
+          raise Core::ValidationError, "prompt must be at most #{max_length} characters" if prompt.length > max_length
+          if Types::LITE_MODELS.include?(model) && prompt.length < PROMPT_MIN_LENGTH_LITE
+            raise Core::ValidationError, "prompt must be between #{PROMPT_MIN_LENGTH_LITE} and #{PROMPT_MAX_LENGTH} characters"
+          end
+
+          raise Core::ValidationError, "source_image_urls is required" unless field_present?(params, :source_image_urls)
+
+          if Types::V4_MODELS.include?(model)
+            validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+            validate_optional!(params, :output_resolution, Types::V4_OUTPUT_RESOLUTIONS)
+            validate_integer_range!(params, :output_count, V4_OUTPUT_COUNT_RANGE)
+            validate_integer!(params, :seed)
+          else
+            validate_required!(params, :aspect_ratio)
+            validate_required!(params, :output_quality)
+            validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+            validate_optional!(params, :output_quality, Types::OUTPUT_QUALITIES)
+          end
+        end
+
+        def validate_required!(params, key)
+          raise Core::ValidationError, "#{key} is required" unless field_present?(params, key)
+        end
+
+        def field_present?(params, key)
+          value = param(params, key)
+          return false if value.nil?
+          return value.any? if value.is_a?(Array)
+          return !value.empty? if value.respond_to?(:empty?)
+
+          true
+        end
+
+        def validate_integer!(params, key)
+          value = param(params, key)
+          return if value.nil?
+          return if value.is_a?(Integer)
+
+          raise Core::ValidationError, "#{key} must be an integer"
+        end
+
+        def validate_integer_range!(params, key, range)
+          value = param(params, key)
+          return if value.nil?
+
+          return if value.is_a?(Integer) && range.cover?(value)
+
+          raise Core::ValidationError, "#{key} must be between #{range.first} and #{range.last}"
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,9 @@
 module RunApi
   module Seedream
     module Resources
+      # Seedream text-to-image generation resource.
+      # Field requirements vary by model: 4.5/5-lite require aspect_ratio and
+      # output_quality; V4 uses output_resolution and supports seed/output_count.
       class TextToImage
         include RunApi::Core::ResourceHelpers
 
@@ -10,7 +13,9 @@ module RunApi
         RESPONSE_CLASS = Types::TextToImageResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTextToImageResponse
         PROMPT_MAX_LENGTH = 3000
+        V4_PROMPT_MAX_LENGTH = 5000
         PROMPT_MIN_LENGTH_LITE = 3
+        V4_OUTPUT_COUNT_RANGE = (1..6)
 
         def initialize(http)
           @http = http
@@ -36,28 +41,32 @@ module RunApi
         def validate_params!(params)
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless model
-          raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::MODELS.join(", ")}" unless Types::MODELS.include?(model)
+          unless Types::TEXT_TO_IMAGE_MODELS.include?(model)
+            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::TEXT_TO_IMAGE_MODELS.join(", ")}"
+          end
 
           prompt = param(params, :prompt)
           raise Core::ValidationError, "prompt is required" unless prompt.is_a?(String) && !prompt.empty?
-          raise Core::ValidationError, "prompt must be at most #{PROMPT_MAX_LENGTH} characters" if prompt.length > PROMPT_MAX_LENGTH
+          max_length = Types::V4_MODELS.include?(model) ? V4_PROMPT_MAX_LENGTH : PROMPT_MAX_LENGTH
+          raise Core::ValidationError, "prompt must be at most #{max_length} characters" if prompt.length > max_length
           if Types::LITE_MODELS.include?(model) && prompt.length < PROMPT_MIN_LENGTH_LITE
             raise Core::ValidationError, "prompt must be between #{PROMPT_MIN_LENGTH_LITE} and #{PROMPT_MAX_LENGTH} characters"
           end
 
-          validate_required!(params, :aspect_ratio)
-          validate_required!(params, :quality)
-          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
-          validate_optional!(params, :quality, Types::QUALITIES)
-
-          if Types::IMAGE_MODELS.include?(model)
-            raise Core::ValidationError, "image_urls is required" unless field_present?(params, :image_urls)
-          elsif field_present?(params, :image_urls)
-            raise Core::ValidationError, "image_urls is not supported for #{model}"
+          if Types::V4_MODELS.include?(model)
+            validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+            validate_optional!(params, :output_resolution, Types::V4_OUTPUT_RESOLUTIONS)
+            validate_integer_range!(params, :output_count, V4_OUTPUT_COUNT_RANGE)
+            validate_integer!(params, :seed)
+          else
+            validate_required!(params, :aspect_ratio)
+            validate_required!(params, :output_quality)
+            validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+            validate_optional!(params, :output_quality, Types::OUTPUT_QUALITIES)
           end
 
-          if field_present?(params, :nsfw_checker) && !Types::LITE_MODELS.include?(model)
-            raise Core::ValidationError, "nsfw_checker is not supported for #{model}"
+          if field_present?(params, :source_image_urls)
+            raise Core::ValidationError, "source_image_urls is not supported for #{model}"
           end
         end
 
@@ -73,6 +82,23 @@ module RunApi
 
           true
         end
+
+        def validate_integer!(params, key)
+          value = param(params, key)
+          return if value.nil?
+          return if value.is_a?(Integer)
+
+          raise Core::ValidationError, "#{key} must be an integer"
+        end
+
+        def validate_integer_range!(params, key, range)
+          value = param(params, key)
+          return if value.nil?
+
+          return if value.is_a?(Integer) && range.cover?(value)
+
+          raise Core::ValidationError, "#{key} must be between #{range.first} and #{range.last}"
+        end
       end
     end
   end

data/lib/runapi/seedream/types.rb

@@ -2,17 +2,25 @@
 
 module RunApi
   module Seedream
+    # Seedream type constants and response models.
+    # Model families differ in supported params: 4.5/5-lite require aspect_ratio
+    # and output_quality; V4 uses output_resolution and supports seed/output_count.
     module Types
       MODELS = %w[
         seedream-4.5-text-to-image
         seedream-4.5-edit
         seedream-5-lite-text-to-image
-        seedream-5-lite-image-to-image
+        seedream-5-lite-edit
+        seedream-v4-text-to-image
+        seedream-v4-edit
       ].freeze
-      IMAGE_MODELS = %w[seedream-4.5-edit seedream-5-lite-image-to-image].freeze
-      LITE_MODELS = %w[seedream-5-lite-text-to-image seedream-5-lite-image-to-image].freeze
+      TEXT_TO_IMAGE_MODELS = %w[seedream-4.5-text-to-image seedream-5-lite-text-to-image seedream-v4-text-to-image].freeze
+      EDIT_MODELS = %w[seedream-4.5-edit seedream-5-lite-edit seedream-v4-edit].freeze
+      LITE_MODELS = %w[seedream-5-lite-text-to-image seedream-5-lite-edit].freeze
+      V4_MODELS = %w[seedream-v4-text-to-image seedream-v4-edit].freeze
       ASPECT_RATIOS = %w[1:1 4:3 3:4 16:9 9:16 2:3 3:2 21:9].freeze
-      QUALITIES = %w[basic high].freeze
+      OUTPUT_QUALITIES = %w[basic high].freeze
+      V4_OUTPUT_RESOLUTIONS = %w[1k 2k 4k].freeze
 
       class Image < RunApi::Core::BaseModel
         optional :url, String
@@ -21,16 +29,20 @@ module RunApi
       class TextToImageResponse < 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
 
+      EditImageResponse = TextToImageResponse
+
       # Narrowed response returned by `text_to_image.run()` once polling observes
       # `status: "completed"`. `images` is required so consumers never have to
       # null-check it on a successful task.
       class CompletedTextToImageResponse < TextToImageResponse
-        required :images, [ -> { Image } ]
+        required :images, [-> { Image }]
       end
+
+      CompletedEditImageResponse = CompletedTextToImageResponse
     end
   end
 end

data/lib/runapi/seedream.rb

@@ -3,6 +3,7 @@
 require "runapi/core"
 require_relative "seedream/types"
 require_relative "seedream/resources/text_to_image"
+require_relative "seedream/resources/edit_image"
 require_relative "seedream/client"
 
 module RunApi

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-seedream
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.7
 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 Seedream SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: The seedream api Ruby SDK is the language-specific package for Seedream
+  on RunAPI. Use this seedream 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-seedream.rb
 - lib/runapi/seedream.rb
 - lib/runapi/seedream/client.rb
+- lib/runapi/seedream/resources/edit_image.rb
 - lib/runapi/seedream/resources/text_to_image.rb
 - lib/runapi/seedream/types.rb
 homepage: https://runapi.ai/models/seedream
@@ -41,7 +47,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/seedream
-  documentation_uri: https://github.com/runapi-ai/seedream-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/seedream-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/seedream-sdk
   changelog_uri: https://github.com/runapi-ai/seedream-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: Seedream API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Seedream API Ruby SDK for RunAPI
 test_files: []