runapi-kling 0.2.12 → 0.2.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60b66152ad919ac0d68333e322d2020f9b6b1494b1595d39cc40bdd3bdde4f16
-  data.tar.gz: a599aa79714ccb068cb43ebedcb3092ed00435185941f4b20a853fdacf9a4524
+  metadata.gz: 3ee363d9aca47d12b9532fe37133181c95bc914e233c127ce86dc7ef9cde3000
+  data.tar.gz: 06e2eea2612c5d2a6eaba6264a7c050d2d61b9cb80c26cfea581139a17baed20
 SHA512:
-  metadata.gz: 0e5605502283c0488cbfcf1a521b14a4cc172d389cbc452fa0c4169afd2ce8fd2e147a0fd5230cac020fd43a91393d1fe1bc578da1238ae3c1425b6a28bb63b6
-  data.tar.gz: 7728476306ee7d0ab8d0877275093548347f60d6c08c831fab3e3f809643e5da95951b5561c0abbafa0ba4b8262ed6e38174f7dd838c845fde2fd52f22889afa
+  metadata.gz: 6bc711db4985a209433276045dfb1174b4295f7256075287da212e98f4f443e8b2670a99f3344410b6441d507cd10465f691b46b97b129b9b22066a7d5a1a085
+  data.tar.gz: b5e93c8807bacc42d3988ee2e1146011733ec0f0d5f9eda7d9fff97b7ad81ed72d6db39f7ee2ba1b2e334c69044026efde4c65fe2f7d250ad37762cb6d6552df

data/README.md

@@ -22,6 +22,23 @@ task = client.text_to_video.create(
 status = client.text_to_video.get(task.id)
 ```
 
+## Kling O1 reference media
+
+```ruby
+result = client.text_to_video.run(
+  model: "kling-o1",
+  prompt: "Keep <<<image_1>>> beside the performer from <<<video_1>>>",
+  reference_image_urls: ["https://cdn.runapi.ai/public/samples/portrait.jpg"],
+  reference_video_url: "https://cdn.runapi.ai/public/samples/video.mp4",
+  reference_video_type: "feature",
+  preserve_reference_video_audio: true,
+  mode: "pro",
+  duration_seconds: 5
+)
+```
+
+Number reference images in prompt order as `<<<image_1>>>`, `<<<image_2>>>`, and so on; the optional video is `<<<video_1>>>`. With a video, send at most four images. Do not combine `last_frame_image_url` with reference images or a reference video. A `feature` reference video may be used with the required first frame; `base` cannot be combined with frame inputs. O1 requests are five seconds and keep sound disabled. Pricing and limits: https://runapi.ai/models/kling/o1.
+
 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.

data/lib/runapi/kling/contract_gen.rb

@@ -86,8 +86,39 @@ module RunApi
         }
       },
       "image-to-video" => {
-        "models" => ["kling-v2.1-master-image-to-video", "kling-v2.1-pro", "kling-v2.1-standard", "kling-v2.5-turbo-image-to-video-pro", "kling-v2.6", "kling-v3-omni", "kling-v3-turbo-image-to-video"],
+        "models" => ["kling-o1", "kling-v2.1-master-image-to-video", "kling-v2.1-pro", "kling-v2.1-standard", "kling-v2.5-turbo-image-to-video-pro", "kling-v2.6", "kling-v3-omni", "kling-v3-turbo-image-to-video"],
         "fields_by_model" => {
+          "kling-o1" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "mode" => {
+              "enum" => ["std", "pro"]
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            },
+            "reference_image_urls" => {
+              "min_items" => 1,
+              "max_items" => 7
+            },
+            "reference_video_type" => {
+              "enum" => ["base", "feature"]
+            }
+          },
           "kling-v2.1-master-image-to-video" => {
             "duration_seconds" => {
               "enum" => [5, 10],
@@ -219,40 +250,45 @@ module RunApi
           }
         },
         "rules" => [{
+          "when" => {
+            "model" => "kling-o1"
+          },
+          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale"]
+        }, {
           "when" => {
             "model" => "kling-v2.1-master-image-to-video"
           },
-          "forbidden" => ["output_resolution", "enable_sound"]
+          "forbidden" => ["output_resolution", "enable_sound", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v2.1-pro"
           },
-          "forbidden" => ["output_resolution", "enable_sound"]
+          "forbidden" => ["output_resolution", "enable_sound", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v2.1-standard"
           },
-          "forbidden" => ["output_resolution", "enable_sound"]
+          "forbidden" => ["output_resolution", "enable_sound", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v2.5-turbo-image-to-video-pro"
           },
-          "forbidden" => ["output_resolution", "enable_sound"]
+          "forbidden" => ["output_resolution", "enable_sound", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v2.6"
           },
-          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale"]
+          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v3-omni"
           },
-          "forbidden" => ["negative_prompt", "cfg_scale"]
+          "forbidden" => ["negative_prompt", "cfg_scale", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v3-turbo-image-to-video"
           },
-          "forbidden" => ["enable_sound", "aspect_ratio", "negative_prompt", "cfg_scale", "last_frame_image_url"]
+          "forbidden" => ["enable_sound", "aspect_ratio", "negative_prompt", "cfg_scale", "last_frame_image_url", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }]
       },
       "motion-control" => {
@@ -310,7 +346,7 @@ module RunApi
         }]
       },
       "text-to-video" => {
-        "models" => ["kling-3.0", "kling-v2.1-master-text-to-video", "kling-v2.5-turbo-text-to-video-pro", "kling-v2.6", "kling-v3-omni", "kling-v3-turbo-text-to-video"],
+        "models" => ["kling-3.0", "kling-o1", "kling-v2.1-master-text-to-video", "kling-v2.5-turbo-text-to-video-pro", "kling-v2.6", "kling-v3-omni", "kling-v3-turbo-text-to-video"],
         "fields_by_model" => {
           "kling-3.0" => {
             "aspect_ratio" => {
@@ -327,6 +363,34 @@ module RunApi
               "enum" => ["720p", "1080p", "4k"]
             }
           },
+          "kling-o1" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5],
+              "type" => "integer"
+            },
+            "mode" => {
+              "enum" => ["std", "pro"]
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            },
+            "reference_image_urls" => {
+              "min_items" => 1,
+              "max_items" => 7
+            },
+            "reference_video_type" => {
+              "enum" => ["base", "feature"]
+            }
+          },
           "kling-v2.1-master-text-to-video" => {
             "aspect_ratio" => {
               "enum" => ["16:9", "9:16", "1:1"]
@@ -416,25 +480,40 @@ module RunApi
           }
         },
         "rules" => [{
+          "when" => {
+            "model" => "kling-3.0"
+          },
+          "forbidden" => ["reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
+        }, {
+          "when" => {
+            "model" => "kling-o1"
+          },
+          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.1-master-text-to-video"
+          },
+          "forbidden" => ["mode", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
+        }, {
           "when" => {
             "model" => "kling-v2.5-turbo-text-to-video-pro"
           },
-          "forbidden" => ["mode"]
+          "forbidden" => ["mode", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v2.6"
           },
-          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements"]
+          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v3-omni"
           },
-          "forbidden" => ["negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements"]
+          "forbidden" => ["negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }, {
           "when" => {
             "model" => "kling-v3-turbo-text-to-video"
           },
-          "forbidden" => ["enable_sound", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements"]
+          "forbidden" => ["enable_sound", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements", "reference_image_urls", "reference_video_url", "reference_video_type", "preserve_reference_video_audio"]
         }]
       }
     }.freeze

data/lib/runapi/kling/resources/image_to_video.rb

@@ -7,6 +7,7 @@ module RunApi
       # Generate videos from an input image.
       class ImageToVideo
         include RunApi::Core::ResourceHelpers
+        include O1ReferenceValidation
 
         ENDPOINT = "/api/v1/kling/image_to_video"
 
@@ -58,6 +59,7 @@ module RunApi
         def validate_params!(params)
           reject_unsupported_v3_turbo_fields!(params)
           validate_contract!(CONTRACT["image-to-video"], params)
+          validate_kling_o1_references!(params)
 
           # Bespoke last-frame rules that the generated contract cannot express.
           model = param(params, :model)
@@ -69,7 +71,7 @@ module RunApi
             return if duration_seconds.to_i == 5
 
             raise Core::ValidationError, "last_frame_image_url requires duration_seconds 5 for #{V3_OMNI_MODEL}"
-          elsif last_frame_image_url && !%w[kling-v2.5-turbo-image-to-video-pro kling-v2.1-pro].include?(model)
+          elsif last_frame_image_url && !%w[kling-o1 kling-v2.5-turbo-image-to-video-pro kling-v2.1-pro].include?(model)
             raise Core::ValidationError, "last_frame_image_url is only supported by kling-v2.5-turbo-image-to-video-pro and kling-v2.1-pro"
           end
         end

data/lib/runapi/kling/resources/o1_reference_validation.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "uri"
+
+module RunApi
+  module Kling
+    module Resources
+      module O1ReferenceValidation
+        O1_MODEL = "kling-o1"
+        O1_IMAGE_EXTENSIONS = %w[.jpg .jpeg .png].freeze
+        O1_VIDEO_EXTENSIONS = %w[.mp4 .mov].freeze
+        O1_NONCANONICAL_IPV4_LITERAL = /\A(?:0x[0-9a-f]+|\d+)(?:\.(?:0x[0-9a-f]+|\d+)){0,3}\z/i
+        O1_BLOCKED_IP_RANGES = %w[
+          0.0.0.0/8
+          10.0.0.0/8
+          100.64.0.0/10
+          127.0.0.0/8
+          169.254.0.0/16
+          172.16.0.0/12
+          192.0.0.0/24
+          192.0.2.0/24
+          192.88.99.0/24
+          192.168.0.0/16
+          198.18.0.0/15
+          198.51.100.0/24
+          203.0.113.0/24
+          224.0.0.0/4
+          240.0.0.0/4
+          255.255.255.255/32
+          ::/128
+          ::1/128
+          64:ff9b::/96
+          64:ff9b:1::/48
+          100::/64
+          2001::/32
+          2001:2::/48
+          2001:db8::/32
+          2002::/16
+          3fff::/20
+          fc00::/7
+          fe80::/10
+          ff00::/8
+        ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+        private
+
+        def validate_kling_o1_references!(params)
+          return unless param(params, :model) == O1_MODEL
+
+          if param(params, :enable_sound) == true
+            raise Core::ValidationError, "enable_sound is not supported by #{O1_MODEL}"
+          end
+
+          validate_o1_frame_urls!(params)
+          prompt = param(params, :prompt)
+          raise Core::ValidationError, "prompt must be a string" unless prompt.is_a?(String)
+          reference_images = Array(param(params, :reference_image_urls))
+          reference_video_url = param(params, :reference_video_url)
+
+          if field_present?(params, :last_frame_image_url) &&
+              (reference_images.any? || field_present?(params, :reference_video_url))
+            raise Core::ValidationError,
+              "last_frame_image_url cannot be combined with reference_image_urls or reference_video_url"
+          end
+
+          if reference_video_url && reference_images.size > 4
+            raise Core::ValidationError, "reference_image_urls must contain at most 4 items when reference_video_url is present"
+          end
+
+          validate_o1_reference_images!(prompt, reference_images)
+          validate_o1_reference_video!(params, prompt, reference_video_url)
+        end
+
+        def validate_o1_frame_urls!(params)
+          %i[first_frame_image_url last_frame_image_url].each do |field|
+            value = param(params, field)
+            next unless value
+            validate_o1_media_url!(
+              value,
+              field: field,
+              extensions: O1_IMAGE_EXTENSIONS,
+              extension_error: "#{field} must use a JPG, JPEG, or PNG URL"
+            )
+          end
+        end
+
+        def validate_o1_reference_images!(prompt, reference_images)
+          reference_images.each_with_index do |url, index|
+            field = "reference_image_urls[#{index}]"
+            raise Core::ValidationError, "#{field} must be a string" unless url.is_a?(String)
+            validate_o1_media_url!(
+              url,
+              field: field,
+              extensions: O1_IMAGE_EXTENSIONS,
+              extension_error: "#{field} must use a JPG, JPEG, or PNG URL"
+            )
+
+            marker = "<<<image_#{index + 1}>>>"
+            unless prompt.include?(marker)
+              raise Core::ValidationError, "prompt must reference reference_image_urls[#{index}] as #{marker}"
+            end
+          end
+
+          prompt.scan(/<<<image_(\d+)>>>/).flatten.map(&:to_i).each do |index|
+            next if index.between?(1, reference_images.size)
+
+            raise Core::ValidationError, "prompt references missing image_#{index}"
+          end
+        end
+
+        def validate_o1_reference_video!(params, prompt, reference_video_url)
+          unless reference_video_url
+            raise Core::ValidationError, "reference_video_type requires reference_video_url" if o1_key?(params, :reference_video_type)
+            if o1_key?(params, :preserve_reference_video_audio)
+              raise Core::ValidationError, "preserve_reference_video_audio requires reference_video_url"
+            end
+            if (match = prompt.match(/<<<video_([^>]+)>>>/))
+              raise Core::ValidationError, "prompt references missing video_#{match[1]}"
+            end
+            return
+          end
+
+          validate_o1_media_url!(
+            reference_video_url,
+            field: :reference_video_url,
+            extensions: O1_VIDEO_EXTENSIONS,
+            extension_error: "reference_video_url must use an MP4 or MOV URL"
+          )
+          unless prompt.include?("<<<video_1>>>")
+            raise Core::ValidationError, "prompt must reference reference_video_url as <<<video_1>>>"
+          end
+          if prompt.scan(/<<<video_([^>]+)>>>/).flatten.any? { |index| index != "1" }
+            raise Core::ValidationError, "prompt may only reference video_1"
+          end
+
+          reference_video_type = param(params, :reference_video_type) || "base"
+          return unless reference_video_type == "base"
+          return unless field_present?(params, :first_frame_image_url) || field_present?(params, :last_frame_image_url)
+
+          raise Core::ValidationError,
+            "reference_video_type base cannot be combined with first_frame_image_url or last_frame_image_url"
+        end
+
+        def o1_key?(params, field)
+          params.key?(field) || params.key?(field.to_s)
+        end
+
+        def validate_o1_media_url!(value, field:, extensions:, extension_error:)
+          raise Core::ValidationError, "#{field} must be a string" unless value.is_a?(String)
+
+          uri = URI.parse(value.to_s)
+          host = uri.hostname
+          local_host = host&.casecmp?("localhost") || host&.downcase&.end_with?(".localhost")
+          valid_http_url = (uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)) &&
+            host && !uri.userinfo && !local_host && !blocked_o1_ip_literal?(host)
+          unless valid_http_url
+            raise Core::ValidationError, "#{field} must be a public HTTP or HTTPS URL"
+          end
+          return if extensions.include?(File.extname(uri.path).downcase)
+
+          raise Core::ValidationError, extension_error
+        rescue URI::InvalidURIError
+          raise Core::ValidationError, "#{field} must be a public HTTP or HTTPS URL"
+        end
+
+        def blocked_o1_ip_literal?(host)
+          ip = IPAddr.new(host).native
+          O1_BLOCKED_IP_RANGES.any? { |range| range.include?(ip) }
+        rescue IPAddr::InvalidAddressError
+          O1_NONCANONICAL_IPV4_LITERAL.match?(host)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/kling/resources/text_to_video.rb

@@ -7,6 +7,7 @@ module RunApi
       # Generate videos from text prompts.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
+        include O1ReferenceValidation
 
         ENDPOINT = "/api/v1/kling/text_to_video"
 
@@ -62,6 +63,7 @@ module RunApi
           reject_unsupported_v3_turbo_fields!(params)
           validate_contract!(CONTRACT["text-to-video"], params)
           validate_v26_params!(params)
+          validate_kling_o1_references!(params)
 
           # Bespoke cross-field rules the contract cannot express.
           multi_shots = param(params, :multi_shots) == true

data/lib/runapi/kling.rb

@@ -3,6 +3,7 @@
 require "runapi/core"
 require_relative "kling/types"
 require_relative "kling/contract_gen"
+require_relative "kling/resources/o1_reference_validation"
 require_relative "kling/resources/text_to_video"
 require_relative "kling/resources/ai_avatar"
 require_relative "kling/resources/image_to_video"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-kling
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.2.13
 platform: ruby
 authors:
 - RunAPI
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.15
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.15
+        version: 0.3.0
 description: The Kling Ruby SDK is the language-specific package for Kling on RunAPI.
   Use this package for video generation, animation, and video editing workflows when
   your application needs request bodies, task status lookup, and consistent RunAPI
@@ -44,6 +44,7 @@ files:
 - lib/runapi/kling/resources/extend_video.rb
 - lib/runapi/kling/resources/image_to_video.rb
 - lib/runapi/kling/resources/motion_control.rb
+- lib/runapi/kling/resources/o1_reference_validation.rb
 - lib/runapi/kling/resources/text_to_video.rb
 - lib/runapi/kling/types.rb
 homepage: https://runapi.ai/models/kling