runapi-seedream 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8ca9b02c90b624e837c7652223020526592784b12d0f0a6f54f7afc6d9ed4d7
-  data.tar.gz: a7b2b5fe72b6135055d4f0838fd9e704f6222c9cd1410615d6b1ca718af078c2
+  metadata.gz: 4e82b3b45f3ff8bc900025adeb9a0390aa67962cc89b301f71fbddfd38c4fe09
+  data.tar.gz: 2092d13fd4d8d1cb37f27e78b6c8423fa7d58e75bcd0588ede104e5a8e8e2004
 SHA512:
-  metadata.gz: f4a3270d5d1920a9151e5d9053aba445e7a07125522e4508a5da35585d9fc69ecbed5681607fe5895bd829ef50b79b8fb16021dfcb7c76174a8e14e5c090cf28
-  data.tar.gz: 2f5cfa1042a0b46d66c70586cd95b24e688eac376699708a8806c8c78bc1ee9aa5abce75eb98f5ef32bbc73985aadad9b99ebead702603dbfef2a2d64cbd60a6
+  metadata.gz: 775b36a48e102429084935f74046ee88703eaed8a1b69e86c1e100de6798166291857e211ba5f317e12a5db2a3aba89b1924c26b1d92508020110ae20583d36d
+  data.tar.gz: 315298e9ecd87fc3ac4209357364a3465944d8607d2cdddb5b03d1e76b46b551ed2fb00133f1a9e974f1e16b562c67e438c5ce16e16492611f60afa8948033d9

data/README.md

@@ -1,8 +1,8 @@
-# Seedream API Ruby SDK for RunAPI
+# Seedream 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.
+The Seedream Ruby SDK is the language-specific package for Seedream on RunAPI. Use this package for image generation, image editing, and creative production workflows when your application needs 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.
+This 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
 
@@ -13,7 +13,7 @@ gem install runapi-seedream
 ## Quick start
 
 ```ruby
-require "runapi-seedream"
+require "runapi/seedream"
 
 client = RunApi::Seedream::Client.new
 task = client.text_to_image.create(
@@ -30,6 +30,10 @@ Use `create` when you want to submit a task and return quickly, `get` when you n
 
 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.
 
+## Seedream 5 Pro
+
+Use `seedream-5-pro-text-to-image` for generation and `seedream-5-pro-edit` for image editing. Both accept `output_quality`, optional `output_format`, and optional content safety checking; editing accepts up to 10 source image URLs.
+
 ## 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.

data/lib/runapi/seedream/contract_gen.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Seedream
+    CONTRACT = {
+      "edit-image" => {
+        "models" => ["seedream-4.5-edit", "seedream-5-lite-edit", "seedream-5-pro-edit", "seedream-v4-edit"],
+        "fields_by_model" => {
+          "seedream-4.5-edit" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_count" => {
+              "type" => "integer"
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "seed" => {
+              "type" => "integer"
+            },
+            "source_image_urls" => {
+              "required" => true
+            }
+          },
+          "seedream-5-lite-edit" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_count" => {
+              "type" => "integer"
+            },
+            "output_format" => {
+              "enum" => ["png", "jpeg"]
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "seed" => {
+              "type" => "integer"
+            },
+            "source_image_urls" => {
+              "required" => true
+            }
+          },
+          "seedream-5-pro-edit" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_format" => {
+              "enum" => ["png", "jpeg"]
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 3,
+              "max" => 5000,
+              "length" => true
+            },
+            "source_image_urls" => {
+              "required" => true
+            }
+          },
+          "seedream-v4-edit" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9"]
+            },
+            "output_count" => {
+              "enum" => [1, 2, 3, 4, 5, 6],
+              "type" => "integer"
+            },
+            "output_resolution" => {
+              "enum" => ["1k", "2k", "4k"]
+            },
+            "seed" => {
+              "type" => "integer"
+            },
+            "source_image_urls" => {
+              "required" => true
+            }
+          }
+        },
+        "rules" => [{
+          "when" => {
+            "model" => "seedream-4.5-edit"
+          },
+          "forbidden" => ["output_format"]
+        }, {
+          "when" => {
+            "model" => "seedream-5-pro-edit"
+          },
+          "forbidden" => ["output_resolution", "output_count", "seed"]
+        }, {
+          "when" => {
+            "model" => "seedream-v4-edit"
+          },
+          "forbidden" => ["output_format"]
+        }]
+      },
+      "text-to-image" => {
+        "models" => ["seedream-4.5-text-to-image", "seedream-5-lite-text-to-image", "seedream-5-pro-text-to-image", "seedream-v4-text-to-image"],
+        "fields_by_model" => {
+          "seedream-4.5-text-to-image" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_count" => {
+              "type" => "integer"
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          },
+          "seedream-5-lite-text-to-image" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_count" => {
+              "type" => "integer"
+            },
+            "output_format" => {
+              "enum" => ["png", "jpeg"]
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          },
+          "seedream-5-pro-text-to-image" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+              "required" => true
+            },
+            "output_format" => {
+              "enum" => ["png", "jpeg"]
+            },
+            "output_quality" => {
+              "enum" => ["basic", "high"],
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 3,
+              "max" => 5000,
+              "length" => true
+            }
+          },
+          "seedream-v4-text-to-image" => {
+            "aspect_ratio" => {
+              "enum" => ["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9"]
+            },
+            "output_count" => {
+              "enum" => [1, 2, 3, 4, 5, 6],
+              "type" => "integer"
+            },
+            "output_resolution" => {
+              "enum" => ["1k", "2k", "4k"]
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          }
+        },
+        "rules" => [{
+          "when" => {
+            "model" => "seedream-4.5-text-to-image"
+          },
+          "forbidden" => ["output_format"]
+        }, {
+          "when" => {
+            "model" => "seedream-5-pro-text-to-image"
+          },
+          "forbidden" => ["output_resolution", "output_count", "seed"]
+        }, {
+          "when" => {
+            "model" => "seedream-v4-text-to-image"
+          },
+          "forbidden" => ["output_format"]
+        }]
+      }
+    }.freeze
+  end
+end

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

@@ -5,7 +5,7 @@ module RunApi
     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.
+      # 5 Pro and V4 accept up to 10 source images; 4.5 and 5-Lite accept up to 14.
       class EditImage
         include RunApi::Core::ResourceHelpers
 
@@ -15,70 +15,48 @@ module RunApi
         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) }
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
         end
 
-        def create(**params)
+        def create(options: nil, **params)
           params = compact_params(params)
           validate_params!(params)
-          request(:post, ENDPOINT, body: params)
+          request(:post, ENDPOINT, body: params, options: options)
         end
 
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
+          validate_contract!(CONTRACT["edit-image"], 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
+          max_length = Types::LONG_PROMPT_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"
+          if Types::MINIMUM_THREE_PROMPT_MODELS.include?(model) && prompt.length < PROMPT_MIN_LENGTH_LITE
+            raise Core::ValidationError, "prompt must be between #{PROMPT_MIN_LENGTH_LITE} and #{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)
+          source_image_urls = param(params, :source_image_urls)
+          source_image_max = Types::TEN_SOURCE_IMAGE_MODELS.include?(model) ? 10 : 14
+          if source_image_urls.is_a?(Array) && source_image_urls.length > source_image_max
+            raise Core::ValidationError, "source_image_urls accepts at most #{source_image_max} images"
           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
+          validate_integer!(params, :seed) if Types::V4_MODELS.include?(model)
         end
 
         def validate_integer!(params, key)
@@ -88,15 +66,6 @@ module RunApi
 
           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/resources/text_to_image.rb

@@ -4,8 +4,8 @@ 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.
+      # Field requirements vary by model: 4.5/5-Lite/5 Pro require aspect_ratio
+      # and output_quality; V4 uses output_resolution and supports seed/output_count.
       class TextToImage
         include RunApi::Core::ResourceHelpers
 
@@ -15,74 +15,48 @@ module RunApi
         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) }
+        def run(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
         end
 
-        def create(**params)
+        def create(options: nil, **params)
           params = compact_params(params)
           validate_params!(params)
-          request(:post, ENDPOINT, body: params)
+          request(:post, ENDPOINT, body: params, options: options)
         end
 
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
+          validate_contract!(CONTRACT["text-to-image"], params)
+
           model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless 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?
-          max_length = Types::V4_MODELS.include?(model) ? V4_PROMPT_MAX_LENGTH : PROMPT_MAX_LENGTH
+          max_length = Types::LONG_PROMPT_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"
+          if Types::MINIMUM_THREE_PROMPT_MODELS.include?(model) && prompt.length < PROMPT_MIN_LENGTH_LITE
+            raise Core::ValidationError, "prompt must be between #{PROMPT_MIN_LENGTH_LITE} and #{max_length} characters"
           end
 
-          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
+          validate_integer!(params, :seed) if Types::V4_MODELS.include?(model)
 
           if field_present?(params, :source_image_urls)
             raise Core::ValidationError, "source_image_urls is not supported for #{model}"
           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?
@@ -90,15 +64,6 @@ module RunApi
 
           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

@@ -3,24 +3,19 @@
 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.
+    # Model families differ in supported params: 4.5/5-Lite/5 Pro require
+    # aspect_ratio and output_quality; 5-Lite/5 Pro also support output_format; 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-edit
-        seedream-v4-text-to-image
-        seedream-v4-edit
-      ].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
+      # Model groupings used by bespoke prompt-length selection (a per-model rule
+      # the contract cannot express). Model membership and field enums are
+      # validated by the generated CONTRACT.
       LITE_MODELS = %w[seedream-5-lite-text-to-image seedream-5-lite-edit].freeze
+      PRO_MODELS = %w[seedream-5-pro-text-to-image seedream-5-pro-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
-      OUTPUT_QUALITIES = %w[basic high].freeze
-      V4_OUTPUT_RESOLUTIONS = %w[1k 2k 4k].freeze
+      LONG_PROMPT_MODELS = (PRO_MODELS + V4_MODELS).freeze
+      MINIMUM_THREE_PROMPT_MODELS = (LITE_MODELS + PRO_MODELS).freeze
+      TEN_SOURCE_IMAGE_MODELS = %w[seedream-5-pro-edit seedream-v4-edit].freeze
 
       class Image < RunApi::Core::BaseModel
         optional :url, String

data/lib/runapi/seedream.rb

@@ -2,6 +2,7 @@
 
 require "runapi/core"
 require_relative "seedream/types"
+require_relative "seedream/contract_gen"
 require_relative "seedream/resources/text_to_image"
 require_relative "seedream/resources/edit_image"
 require_relative "seedream/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-seedream
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.13
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        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.
+        version: 0.2.13
+description: The Seedream Ruby SDK is the language-specific package for Seedream on
+  RunAPI. Use this package for image generation, image editing, and creative production
+  workflows when your application needs request bodies, task status lookup, and consistent
+  RunAPI errors in Ruby.
 email:
 - contact@runapi.ai
 executables: []
@@ -39,6 +39,7 @@ files:
 - lib/runapi-seedream.rb
 - lib/runapi/seedream.rb
 - lib/runapi/seedream/client.rb
+- lib/runapi/seedream/contract_gen.rb
 - lib/runapi/seedream/resources/edit_image.rb
 - lib/runapi/seedream/resources/text_to_image.rb
 - lib/runapi/seedream/types.rb
@@ -46,9 +47,11 @@ homepage: https://runapi.ai/models/seedream
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: seedream
   homepage_uri: https://runapi.ai/models/seedream
   documentation_uri: https://github.com/runapi-ai/seedream-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/seedream-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/seedream-sdk/issues
   changelog_uri: https://github.com/runapi-ai/seedream-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -66,5 +69,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Seedream API Ruby SDK for RunAPI
+summary: Seedream Ruby SDK for RunAPI
 test_files: []