runapi-kling 0.2.4 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15dc6670d6a88eff6385d1b29b2f413edf0b6fee71f1c9ed359739934119ac79
-  data.tar.gz: 8988cd7485fd0c33d1ff69c6881681a712ccab07b1c90c2d3e0edc082f8dc0b6
+  metadata.gz: '06496c392220522b5dedc8acd4f71436ba22fd51df6ac685d8600fc5a5f3d02f'
+  data.tar.gz: ba507498208a38a168ec79b1e7a1041c95101c5aa510f1ba11cd55a3cd6e4a1a
 SHA512:
-  metadata.gz: c7960d362b6603113936756f8a6f4aa035c1730f8df179746f61cc55840c0baa35c645c4e811c225e50d1c24304feb42720939e4bc031dae73eff56c7757b046
-  data.tar.gz: 04e1ed432f1935db93bd3b5b0f94f8e16b88c2fbddd80b965fd4beb0d9402784b81758936566291b321e0d3c7e4c1cc784ffeb0083b7259011c9c6a08a81e065
+  metadata.gz: 361d632584c9a124c7e295bd3ae2f337f0434166ee76e13871afc5e17a96fc11e30f86802daa65724f1c8ee421cc4638ab97329cacce8dff1e14a701f12e0f89
+  data.tar.gz: 2a4358323094f9d1d2269b857107927042707cb003df73abb7855d3305cf30d1bcf5e09bda2799dec94da92ca85fc72d5eb5ac334e448de688749ac81a16daba

data/README.md

@@ -0,0 +1,45 @@
+# Kling AI 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.
+
+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.
+
+## Install
+
+```bash
+gem install runapi-kling
+```
+
+## Quick start
+
+```ruby
+require "runapi-kling"
+
+client = RunApi::Kling::Client.new
+task = client.generations.create(
+  # Pass the Kling JSON request body from https://runapi.ai/docs#kling.
+)
+status = client.generations.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::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.
+
+## Links
+
+- Model page: https://runapi.ai/models/kling
+- SDK docs: https://runapi.ai/docs#sdk-kling
+- Product docs: https://runapi.ai/docs#kling
+- Pricing and rate limits: https://runapi.ai/models/kling/3.0
+- Provider comparison: https://runapi.ai/providers/kuaishou
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/kling-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/kling/client.rb

@@ -9,7 +9,7 @@ module RunApi
     #   result = client.text_to_video.run(
     #     model: "kling-3.0", prompt: "A cat walking through a garden"
     #   )
-    class Client
+    class Client < RunApi::Core::Client
       # @return [Resources::TextToVideo] Text-to-video operations.
       attr_reader :text_to_video
       # @return [Resources::AiAvatar] AI avatar generation operations.
@@ -20,10 +20,7 @@ module RunApi
       attr_reader :motion_control
 
       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_video = Resources::TextToVideo.new(http)
         @ai_avatar = Resources::AiAvatar.new(http)
         @image_to_video = Resources::ImageToVideo.new(http)

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

@@ -53,8 +53,8 @@ module RunApi
             raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::AI_AVATAR_MODELS.join(", ")}"
           end
 
-          raise Core::ValidationError, "image_url is required" unless param(params, :image_url)
-          raise Core::ValidationError, "audio_url is required" unless param(params, :audio_url)
+          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)
         end
       end

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

@@ -54,7 +54,17 @@ module RunApi
           end
 
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "image_url is required" unless param(params, :image_url)
+          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(", ")}"
+          end
+
+          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
         end
       end
     end

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

@@ -49,15 +49,18 @@ module RunApi
         def validate_params!(params)
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless model
-          unless Types::MODELS.include?(model)
-            raise Core::ValidationError, "Invalid model: #{model}. Must be one of: #{Types::MODELS.join(", ")}"
+          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)
 
-          input_urls = param(params, :input_urls)
-          raise Core::ValidationError, "input_urls is required" unless input_urls.is_a?(Array) && input_urls.any?
+          source_image_url = param(params, :source_image_url)
+          raise Core::ValidationError, "source_image_url is required" unless source_image_url
 
-          video_urls = param(params, :video_urls)
-          raise Core::ValidationError, "video_urls is required" unless video_urls.is_a?(Array) && video_urls.any?
+          reference_video_url = param(params, :reference_video_url)
+          raise Core::ValidationError, "reference_video_url is required" unless reference_video_url
         end
       end
     end

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

@@ -56,7 +56,8 @@ module RunApi
           multi_shots = param(params, :multi_shots) == true
 
           if multi_shots
-            raise Core::ValidationError, "sound must be true when multi_shots is true" unless param(params, :sound) == true
+            raise Core::ValidationError, "enable_sound must be true when multi_shots is true" unless param(params, :enable_sound) == true
+            raise Core::ValidationError, "last_frame_image_url is not supported when multi_shots is true" if param(params, :last_frame_image_url)
 
             multi_prompt = param(params, :multi_prompt)
             validate_multi_prompt!(multi_prompt)
@@ -64,14 +65,18 @@ module RunApi
             raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
           end
 
-          validate_optional!(params, :mode, Types::MODES)
+          validate_optional!(params, :output_resolution, Types::TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS)
           validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
 
-          duration = param(params, :duration)
-          if duration
-            dur_int = duration.to_i
-            unless Types::DURATION_RANGE.cover?(dur_int)
-              raise Core::ValidationError, "Invalid duration: #{duration}. Must be an integer between #{Types::DURATION_RANGE.min} and #{Types::DURATION_RANGE.max}"
+          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
         end
@@ -83,7 +88,7 @@ module RunApi
 
           multi_prompt.each_with_index do |shot, index|
             prompt = shot.is_a?(Hash) ? (shot[:prompt] || shot["prompt"]) : nil
-            duration = shot.is_a?(Hash) ? (shot[:duration] || shot["duration"]) : nil
+            duration_seconds = shot.is_a?(Hash) ? (shot[:duration_seconds] || shot["duration_seconds"]) : nil
 
             raise Core::ValidationError, "multi_prompt[#{index}].prompt is required" if prompt.nil? || prompt.empty?
 
@@ -91,11 +96,11 @@ module RunApi
               raise Core::ValidationError, "multi_prompt[#{index}].prompt exceeds #{Types::MULTI_PROMPT_MAX_LENGTH} characters"
             end
 
-            raise Core::ValidationError, "multi_prompt[#{index}].duration is required" if duration.nil?
+            raise Core::ValidationError, "multi_prompt[#{index}].duration_seconds is required" if duration_seconds.nil?
 
-            dur_int = duration.to_i
+            dur_int = duration_seconds.to_i
             unless Types::MULTI_PROMPT_DURATION_RANGE.cover?(dur_int)
-              raise Core::ValidationError, "multi_prompt[#{index}].duration must be between #{Types::MULTI_PROMPT_DURATION_RANGE.min} and #{Types::MULTI_PROMPT_DURATION_RANGE.max}"
+              raise Core::ValidationError, "multi_prompt[#{index}].duration_seconds must be between #{Types::MULTI_PROMPT_DURATION_RANGE.min} and #{Types::MULTI_PROMPT_DURATION_RANGE.max}"
             end
           end
         end

data/lib/runapi/kling/types.rb

@@ -2,23 +2,60 @@
 
 module RunApi
   module Kling
+    # Type definitions and constants for Kling video generation.
     module Types
-      TEXT_TO_VIDEO_MODELS = %w[kling-3.0 kling-v2.5-turbo-text-to-video-pro].freeze
-
-      AI_AVATAR_MODELS = %w[kling-ai-avatar-pro kling-ai-avatar-standard].freeze
-
-      IMAGE_TO_VIDEO_MODELS = %w[kling-v2.5-turbo-image-to-video-pro].freeze
-
-      MODES = %w[std pro].freeze
+      # 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).
       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
 
+      # A generated video file with a download URL.
       class Video < RunApi::Core::BaseModel
         optional :url, String
       end
@@ -29,22 +66,22 @@ module RunApi
       end
 
       class TextToVideoResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
+        optional :videos, [-> { Video }]
         optional :error, String
       end
 
       class AiAvatarResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
+        optional :videos, [-> { Video }]
         optional :error, String
       end
 
       class ImageToVideoResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
+        optional :videos, [-> { Video }]
         optional :error, String
       end
 
       class MotionControlResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
+        optional :videos, [-> { Video }]
         optional :error, String
       end
 
@@ -52,19 +89,19 @@ module RunApi
       # `status: "completed"`. `videos` is required so consumers never have to
       # null-check it on a successful task.
       class CompletedTextToVideoResponse < TextToVideoResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
 
       class CompletedAiAvatarResponse < AiAvatarResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
 
       class CompletedImageToVideoResponse < ImageToVideoResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
 
       class CompletedMotionControlResponse < MotionControlResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-kling
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.8
 platform: ruby
 authors:
 - RunAPI
@@ -15,22 +15,27 @@ 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 Kling SDK for JavaScript, Ruby, and Go
+        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.
 email:
 - contact@runapi.ai
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
+- README.md
 - lib/runapi-kling.rb
 - lib/runapi/kling.rb
 - lib/runapi/kling/client.rb
@@ -44,7 +49,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/kling
-  documentation_uri: https://github.com/runapi-ai/kling-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/kling-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/kling-sdk
   changelog_uri: https://github.com/runapi-ai/kling-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -63,5 +68,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Kling API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Kling AI API Ruby SDK for RunAPI
 test_files: []