runapi-kling 0.2.8 → 0.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '06496c392220522b5dedc8acd4f71436ba22fd51df6ac685d8600fc5a5f3d02f'
-  data.tar.gz: ba507498208a38a168ec79b1e7a1041c95101c5aa510f1ba11cd55a3cd6e4a1a
+  metadata.gz: e320ba4bacde45051ec892890b4538a8fe2c415d86facc8c3c950bfeb43bd94e
+  data.tar.gz: 4ae9148e0a4b579a47f65c6b02ba40d3cc1c95bec9254fd423bf45b442ea99f3
 SHA512:
-  metadata.gz: 361d632584c9a124c7e295bd3ae2f337f0434166ee76e13871afc5e17a96fc11e30f86802daa65724f1c8ee421cc4638ab97329cacce8dff1e14a701f12e0f89
-  data.tar.gz: 2a4358323094f9d1d2269b857107927042707cb003df73abb7855d3305cf30d1bcf5e09bda2799dec94da92ca85fc72d5eb5ac334e448de688749ac81a16daba
+  metadata.gz: c1bc8ee1eb14d11292751fa2c24318335bb07b4a7bfa02b82454c30f9da7889281bf29067d5fc34d7d29c337d12fbadf934924c9a61c7df34b64bfe6ad937939
+  data.tar.gz: e64c06c27bebb03e97c45801a268ad752ab63a3b22cd24e85b7d3baf9d8fc4f7b16cb0547336c820c7a5c560a326fbf49614bf6806e6e9d3e9ec4561e486265d

data/README.md

@@ -1,8 +1,8 @@
-# Kling AI API Ruby SDK for RunAPI
+# Kling API Ruby SDK for RunAPI
 
-The kling ai api Ruby SDK is the language-specific package for Kling on RunAPI. Use this kling ai api package for text-to-video, image-to-video, video editing, and animation flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+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 errors in Ruby.
 
-This kling ai api README is the Ruby package guide inside the public `kling-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/kling; for API reference, use https://runapi.ai/docs#kling; for SDK docs, use https://runapi.ai/docs#sdk-kling.
+This README is the Ruby package guide inside the public `kling-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/kling; for API reference, use https://runapi.ai/docs#kling; for SDK docs, use https://runapi.ai/docs#sdk-kling.
 
 ## Install
 
@@ -13,13 +13,13 @@ gem install runapi-kling
 ## Quick start
 
 ```ruby
-require "runapi-kling"
+require "runapi/kling"
 
 client = RunApi::Kling::Client.new
-task = client.generations.create(
+task = client.text_to_video.create(
   # Pass the Kling JSON request body from https://runapi.ai/docs#kling.
 )
-status = client.generations.get(task.id)
+status = client.text_to_video.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.
@@ -28,7 +28,7 @@ RunAPI-generated file URLs are temporary. Download and store generated images, v
 
 ## Language notes
 
-Use Ruby keyword arguments and the `RunApi::Kling` error classes when building video jobs, Rails workers, or scripts. The available resources include text-to-video, image-to-video, AI avatars, V2.1/V2.5 video variants, and motion controls. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+Use Ruby keyword arguments and the `RunApi::Kling` error classes when building video jobs, Rails workers, or scripts. The available resources are `text_to_video`, `ai_avatar`, `image_to_video`, and `motion_control`. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
 
 ## Links
 

data/lib/runapi/kling/contract_gen.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Kling
+    CONTRACT = {
+      "avatar" => {
+        "models" => ["kling-ai-avatar-pro", "kling-ai-avatar-standard", "kling-ai-avatar-v1-pro", "kling-v1-avatar-standard"],
+        "fields_by_model" => {
+          "kling-ai-avatar-pro" => {
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            },
+            "source_audio_url" => {
+              "required" => true
+            },
+            "source_image_url" => {
+              "required" => true
+            }
+          },
+          "kling-ai-avatar-standard" => {
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            },
+            "source_audio_url" => {
+              "required" => true
+            },
+            "source_image_url" => {
+              "required" => true
+            }
+          },
+          "kling-ai-avatar-v1-pro" => {
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            },
+            "source_audio_url" => {
+              "required" => true
+            },
+            "source_image_url" => {
+              "required" => true
+            }
+          },
+          "kling-v1-avatar-standard" => {
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            },
+            "source_audio_url" => {
+              "required" => true
+            },
+            "source_image_url" => {
+              "required" => true
+            }
+          }
+        }
+      },
+      "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-turbo-image-to-video"],
+        "fields_by_model" => {
+          "kling-v2.1-master-image-to-video" => {
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            }
+          },
+          "kling-v2.1-pro" => {
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            }
+          },
+          "kling-v2.1-standard" => {
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            }
+          },
+          "kling-v2.5-turbo-image-to-video-pro" => {
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            }
+          },
+          "kling-v2.6" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "mode" => {
+              "enum" => ["std", "pro"]
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            }
+          },
+          "kling-v3-turbo-image-to-video" => {
+            "duration_seconds" => {
+              "enum" => [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "model" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            }
+          }
+        },
+        "rules" => [{
+          "when" => {
+            "model" => "kling-v2.1-master-image-to-video"
+          },
+          "forbidden" => ["output_resolution", "mode", "enable_sound"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.1-pro"
+          },
+          "forbidden" => ["output_resolution", "mode", "enable_sound"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.1-standard"
+          },
+          "forbidden" => ["output_resolution", "mode", "enable_sound"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.5-turbo-image-to-video-pro"
+          },
+          "forbidden" => ["output_resolution", "mode", "enable_sound"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.6"
+          },
+          "forbidden" => ["output_resolution", "negative_prompt", "cfg_scale"]
+        }, {
+          "when" => {
+            "model" => "kling-v3-turbo-image-to-video"
+          },
+          "forbidden" => ["mode", "enable_sound", "aspect_ratio", "negative_prompt", "cfg_scale", "last_frame_image_url"]
+        }]
+      },
+      "motion-control" => {
+        "models" => ["kling-3.0"],
+        "fields_by_model" => {
+          "kling-3.0" => {
+            "background_source" => {
+              "enum" => ["video", "image"]
+            },
+            "character_orientation" => {
+              "enum" => ["video", "image"]
+            },
+            "model" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "reference_video_url" => {
+              "required" => true
+            },
+            "source_image_url" => {
+              "required" => true
+            }
+          }
+        }
+      },
+      "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-turbo-text-to-video"],
+        "fields_by_model" => {
+          "kling-3.0" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+              "type" => "integer"
+            },
+            "model" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p", "4k"]
+            }
+          },
+          "kling-v2.1-master-text-to-video" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "model" => {
+              "required" => true
+            }
+          },
+          "kling-v2.5-turbo-text-to-video-pro" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "model" => {
+              "required" => true
+            }
+          },
+          "kling-v2.6" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "type" => "integer"
+            },
+            "mode" => {
+              "enum" => ["std", "pro"]
+            },
+            "model" => {
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            }
+          },
+          "kling-v3-turbo-text-to-video" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1"]
+            },
+            "duration_seconds" => {
+              "enum" => [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+              "type" => "integer"
+            },
+            "model" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "prompt" => {
+              "required" => true,
+              "min" => 1,
+              "max" => 2500,
+              "length" => true
+            }
+          }
+        },
+        "rules" => [{
+          "when" => {
+            "model" => "kling-3.0"
+          },
+          "forbidden" => ["mode"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.1-master-text-to-video"
+          },
+          "forbidden" => ["mode"]
+        }, {
+          "when" => {
+            "model" => "kling-v2.5-turbo-text-to-video-pro"
+          },
+          "forbidden" => ["mode"]
+        }, {
+          "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"]
+        }, {
+          "when" => {
+            "model" => "kling-v3-turbo-text-to-video"
+          },
+          "forbidden" => ["mode", "enable_sound", "negative_prompt", "cfg_scale", "multi_shots", "multi_prompt", "first_frame_image_url", "last_frame_image_url", "kling_elements"]
+        }]
+      }
+    }.freeze
+  end
+end

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

@@ -21,41 +21,33 @@ module RunApi
         #
         # @param params [Hash] AI avatar parameters
         # @return [RunApi::Kling::Types::CompletedAiAvatarResponse] completed task with videos
-        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
 
         # Create an AI avatar generation task.
         #
         # @param params [Hash] AI avatar parameters
         # @return [RunApi::Kling::Types::AiAvatarResponse] task creation result with id
-        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
 
         # Get AI avatar task status by task ID.
         #
         # @param id [String] task ID
         # @return [RunApi::Kling::Types::AiAvatarResponse] current task status
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
-          model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless model
-          unless Types::AI_AVATAR_MODELS.include?(model)
-            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::AI_AVATAR_MODELS.join(", ")}"
-          end
-
-          raise Core::ValidationError, "source_image_url is required" unless param(params, :source_image_url)
-          raise Core::ValidationError, "source_audio_url is required" unless param(params, :source_audio_url)
-          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
+          validate_contract!(CONTRACT["avatar"], params)
         end
       end
     end

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

@@ -12,6 +12,14 @@ module RunApi
 
         RESPONSE_CLASS = Types::ImageToVideoResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedImageToVideoResponse
+        V26_MODEL = "kling-v2.6"
+        V3_TURBO_MODEL = "kling-v3-turbo-image-to-video"
+        V3_TURBO_UNSUPPORTED_FIELDS = %i[
+          aspect_ratio
+          negative_prompt
+          cfg_scale
+          last_frame_image_url
+        ].freeze
 
         def initialize(http)
           @http = http
@@ -21,50 +29,66 @@ module RunApi
         #
         # @param params [Hash] image-to-video parameters
         # @return [RunApi::Kling::Types::CompletedImageToVideoResponse] completed task with videos
-        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
 
         # Create an image-to-video task.
         #
         # @param params [Hash] image-to-video parameters
         # @return [RunApi::Kling::Types::ImageToVideoResponse] task creation result with id
-        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
 
         # Get image-to-video task status by task ID.
         #
         # @param id [String] task ID
         # @return [RunApi::Kling::Types::ImageToVideoResponse] current task status
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
+          reject_unsupported_v3_turbo_fields!(params)
+          validate_contract!(CONTRACT["image-to-video"], params)
+
+          # Bespoke: last_frame_image_url is only allowed for select models
+          # (model-gating, not expressible as a contract enum/required rule).
           model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless model
-          unless Types::IMAGE_TO_VIDEO_MODELS.include?(model)
-            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::IMAGE_TO_VIDEO_MODELS.join(", ")}"
+          last_frame_image_url = param(params, :last_frame_image_url)
+          if model == V26_MODEL
+            validate_v26_params!(params, last_frame_image_url)
+          elsif last_frame_image_url && !%w[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
 
-          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "first_frame_image_url is required" unless param(params, :first_frame_image_url)
-
-          duration_seconds = param(params, :duration_seconds)
-          if duration_seconds && !Types::FIXED_DURATIONS.include?(duration_seconds)
-            raise Core::ValidationError, "Invalid duration_seconds: #{duration_seconds}. Must be one of: #{Types::FIXED_DURATIONS.join(", ")}"
+        def validate_v26_params!(params, last_frame_image_url)
+          mode = param(params, :mode) || "std"
+          if param(params, :enable_sound) == true && mode != "pro"
+            raise Core::ValidationError, "enable_sound requires mode pro for #{V26_MODEL}"
           end
+          return unless last_frame_image_url
 
-          last_frame_image_url = param(params, :last_frame_image_url)
-          if last_frame_image_url && !%w[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
+          raise Core::ValidationError, "last_frame_image_url requires mode pro for #{V26_MODEL}" unless mode == "pro"
+
+          duration_seconds = param(params, :duration_seconds) || 5
+          return if duration_seconds.to_i == 5
+
+          raise Core::ValidationError, "last_frame_image_url requires duration_seconds 5 for #{V26_MODEL}"
+        end
+
+        def reject_unsupported_v3_turbo_fields!(params)
+          return unless param(params, :model) == V3_TURBO_MODEL
+
+          field = V3_TURBO_UNSUPPORTED_FIELDS.find { |candidate| field_present?(params, candidate) }
+          raise Core::ValidationError, "#{field} is not supported by #{V3_TURBO_MODEL}" if field
         end
       end
     end

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

@@ -21,46 +21,33 @@ module RunApi
         #
         # @param params [Hash] motion control parameters
         # @return [RunApi::Kling::Types::CompletedMotionControlResponse] completed task with videos
-        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
 
         # Create a motion control generation task.
         #
         # @param params [Hash] motion control parameters
         # @return [RunApi::Kling::Types::MotionControlResponse] task creation result with id
-        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
 
         # Get motion control task status by task ID.
         #
         # @param id [String] task ID
         # @return [RunApi::Kling::Types::MotionControlResponse] current task status
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
-          model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless model
-          unless Types::MOTION_CONTROL_MODELS.include?(model)
-            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::MOTION_CONTROL_MODELS.join(", ")}"
-          end
-          validate_optional!(params, :output_resolution, Types::MOTION_CONTROL_OUTPUT_RESOLUTIONS)
-          validate_optional!(params, :character_orientation, Types::MOTION_CONTROL_CHARACTER_ORIENTATIONS)
-          validate_optional!(params, :background_source, Types::MOTION_CONTROL_BACKGROUND_SOURCES)
-
-          source_image_url = param(params, :source_image_url)
-          raise Core::ValidationError, "source_image_url is required" unless source_image_url
-
-          reference_video_url = param(params, :reference_video_url)
-          raise Core::ValidationError, "reference_video_url is required" unless reference_video_url
+          validate_contract!(CONTRACT["motion-control"], params)
         end
       end
     end

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

@@ -12,6 +12,18 @@ module RunApi
 
         RESPONSE_CLASS = Types::TextToVideoResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTextToVideoResponse
+        V26_MODEL = "kling-v2.6"
+        V3_TURBO_MODEL = "kling-v3-turbo-text-to-video"
+        V3_TURBO_UNSUPPORTED_FIELDS = %i[
+          enable_sound
+          negative_prompt
+          cfg_scale
+          multi_shots
+          multi_prompt
+          first_frame_image_url
+          last_frame_image_url
+          kling_elements
+        ].freeze
 
         def initialize(http)
           @http = http
@@ -21,38 +33,37 @@ module RunApi
         #
         # @param params [Hash] text-to-video parameters
         # @return [RunApi::Kling::Types::CompletedTextToVideoResponse] completed task with videos
-        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
 
         # Create a text-to-video task.
         #
         # @param params [Hash] text-to-video parameters
         # @return [RunApi::Kling::Types::TextToVideoResponse] task creation result with id
-        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
 
         # Get text-to-video task status by task ID.
         #
         # @param id [String] task ID
         # @return [RunApi::Kling::Types::TextToVideoResponse] current task status
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
 
         private
 
         def validate_params!(params)
-          model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless model
-          unless Types::TEXT_TO_VIDEO_MODELS.include?(model)
-            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::TEXT_TO_VIDEO_MODELS.join(", ")}"
-          end
+          reject_unsupported_v3_turbo_fields!(params)
+          validate_contract!(CONTRACT["text-to-video"], params)
+          validate_v26_params!(params)
 
+          # Bespoke cross-field rules the contract cannot express.
           multi_shots = param(params, :multi_shots) == true
 
           if multi_shots
@@ -64,21 +75,20 @@ module RunApi
           else
             raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
           end
+        end
 
-          validate_optional!(params, :output_resolution, Types::TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS)
-          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
+        def validate_v26_params!(params)
+          return unless param(params, :model) == V26_MODEL
+          return unless param(params, :enable_sound) == true && param(params, :mode) != "pro"
 
-          duration_seconds = param(params, :duration_seconds)
-          if duration_seconds
-            dur_int = duration_seconds.to_i
-            if model == "kling-v2.1-master-text-to-video" || model == "kling-v2.5-turbo-text-to-video-pro"
-              unless Types::FIXED_DURATIONS.include?(duration_seconds)
-                raise Core::ValidationError, "Invalid duration_seconds: #{duration_seconds}. Must be one of: #{Types::FIXED_DURATIONS.join(", ")}"
-              end
-            elsif !Types::DURATION_RANGE.cover?(dur_int)
-              raise Core::ValidationError, "Invalid duration_seconds: #{duration_seconds}. Must be an integer between #{Types::DURATION_RANGE.min} and #{Types::DURATION_RANGE.max}"
-            end
-          end
+          raise Core::ValidationError, "enable_sound requires mode pro for #{V26_MODEL}"
+        end
+
+        def reject_unsupported_v3_turbo_fields!(params)
+          return unless param(params, :model) == V3_TURBO_MODEL
+
+          field = V3_TURBO_UNSUPPORTED_FIELDS.find { |candidate| field_present?(params, candidate) }
+          raise Core::ValidationError, "#{field} is not supported by #{V3_TURBO_MODEL}" if field
         end
 
         def validate_multi_prompt!(multi_prompt)

data/lib/runapi/kling/types.rb

@@ -4,54 +4,10 @@ module RunApi
   module Kling
     # Type definitions and constants for Kling video generation.
     module Types
-      # Text-to-video model variants. kling-3.0 supports multi-shot, sound, and elements;
-      # V2.x models support negative prompts and cfg_scale.
-      TEXT_TO_VIDEO_MODELS = %w[
-        kling-3.0
-        kling-v2.5-turbo-text-to-video-pro
-        kling-v2.1-master-text-to-video
-      ].freeze
-
-      # AI avatar lip-sync quality tiers, from highest to fastest.
-      AI_AVATAR_MODELS = %w[
-        kling-ai-avatar-pro
-        kling-ai-avatar-standard
-        kling-ai-avatar-v1-pro
-        kling-v1-avatar-standard
-      ].freeze
-
-      # Image-to-video model variants. V2.5 turbo and V2.1 pro support last-frame image control.
-      IMAGE_TO_VIDEO_MODELS = %w[
-        kling-v2.5-turbo-image-to-video-pro
-        kling-v2.1-pro
-        kling-v2.1-standard
-        kling-v2.1-master-image-to-video
-      ].freeze
-
-      # Output resolution options. 4k is highest quality but slowest.
-      TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS = %w[720p 1080p 4k].freeze
-
-      MOTION_CONTROL_MODELS = %w[kling-3.0].freeze
-
-      MOTION_CONTROL_OUTPUT_RESOLUTIONS = %w[720p 1080p].freeze
-
-      # Whether the character faces the direction from the video or the image.
-      MOTION_CONTROL_CHARACTER_ORIENTATIONS = %w[video image].freeze
-
-      # Whether the background comes from the reference video or the subject image.
-      MOTION_CONTROL_BACKGROUND_SOURCES = %w[video image].freeze
-
-      ASPECT_RATIOS = %w[16:9 9:16 1:1].freeze
-
-      # Duration range for kling-3.0 (seconds).
-      DURATION_RANGE = (3..15)
-
-      # Per-shot duration range in multi-shot mode (seconds).
+      # Per-shot duration range in multi-shot mode (seconds). Bespoke constant for
+      # the multi_prompt[] nested-array validation, which the contract cannot express.
       MULTI_PROMPT_DURATION_RANGE = (1..12)
 
-      # Fixed duration options for V2.x models (seconds).
-      FIXED_DURATIONS = [5, 10].freeze
-
       # Maximum character length for each multi-shot prompt segment.
       MULTI_PROMPT_MAX_LENGTH = 500
 

data/lib/runapi/kling.rb

@@ -2,6 +2,7 @@
 
 require "runapi/core"
 require_relative "kling/types"
+require_relative "kling/contract_gen"
 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.8
+  version: 0.2.10
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.6
+        version: 0.2.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.6
-description: The kling ai api Ruby SDK is the language-specific package for Kling
-  on RunAPI. Use this kling ai api package for text-to-video, image-to-video, video
-  editing, and animation flows when your application needs JSON request bodies, task
-  status lookup, and consistent RunAPI errors in Ruby.
+        version: 0.2.14
+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
+  errors in Ruby.
 email:
 - contact@runapi.ai
 executables: []
@@ -39,6 +39,7 @@ files:
 - lib/runapi-kling.rb
 - lib/runapi/kling.rb
 - lib/runapi/kling/client.rb
+- lib/runapi/kling/contract_gen.rb
 - lib/runapi/kling/resources/ai_avatar.rb
 - lib/runapi/kling/resources/image_to_video.rb
 - lib/runapi/kling/resources/motion_control.rb
@@ -48,9 +49,11 @@ homepage: https://runapi.ai/models/kling
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: kling
   homepage_uri: https://runapi.ai/models/kling
   documentation_uri: https://github.com/runapi-ai/kling-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/kling-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/kling-sdk/issues
   changelog_uri: https://github.com/runapi-ai/kling-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -68,5 +71,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Kling AI API Ruby SDK for RunAPI
+summary: Kling API Ruby SDK for RunAPI
 test_files: []