runapi-happyhorse 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c4f0f454f1eb15878f3c4edd3f7d958db1777e5ffb6260c0f29e0774fa587bd
-  data.tar.gz: 0c0f9d96f07ed1d893a531df62c42f5c2896b1c61d56e751635b973d7608d6f0
+  metadata.gz: f6dce8cdd8d38b5c1062594b3de7c673544d2558abe8db1c616b35e81ae1c9bc
+  data.tar.gz: c2ab10637f4c26d08b77e6b44dc80eb51be19c99b6ba34d610656426771b6555
 SHA512:
-  metadata.gz: 1464ac2c22e0349fdb59df6a910a8afd1ae31be12831847359182b09da136ed7e332f9a3df0d32bbe2a5ada0c711a2e78eb14f3ecb509e8f5e25640100de8490
-  data.tar.gz: 0cc07a34f20984589248c3571a528e35085194557e5477fbed9b524ecc78dacf308511dc0a68750488ff5da5c926b454d42e7be743d51d8b061ce587fd3c6975
+  metadata.gz: 6e19584b1a78ef79a9d869b5eef458afd4fb5b7b7d87d395db073e7654caf27bdc0a656b97851796cc0d7eb979113c9a1aa555cfa0c67d875c395dc2c6ee5be6
+  data.tar.gz: cd1e0d2335573a8ac73d3df65640555fc0afb3f4bc1427c1bf1386d232a209769f3a7a94a68eee82c86d9910be40b5927427beb3f07e535ee6f993ab30c5c8e6

data/README.md

@@ -1,6 +1,6 @@
 # HappyHorse API Ruby SDK for RunAPI
 
-The happyhorse ai api Ruby SDK is the language-specific package for HappyHorse on RunAPI. Use this package for text, image, and edit-video workflows that need JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+The HappyHorse Ruby SDK is the language-specific package for HappyHorse 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.
 
 ## Install
 
@@ -26,6 +26,8 @@ video = client.text_to_video.run(
 
 For image-to-video, call `client.image_to_video.run` with `model: "happyhorse-image-to-video"` and exactly one `image_urls` entry. For character-guided text-to-video, call `client.text_to_video.run` with `model: "happyhorse-character"` and 1-9 `reference_image_urls` entries. For edit-video, call `client.edit_video.run` with `model: "happyhorse-edit-video"`, one `video_url`, and optional `reference_image` entries.
 
+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.
+
 ## Links
 
 - Model page: https://runapi.ai/models/happyhorse

data/lib/runapi/happyhorse/client.rb

@@ -2,14 +2,23 @@
 
 module RunApi
   module HappyHorse
-    class Client
-      attr_reader :text_to_video, :image_to_video, :edit_video
+    # HappyHorse video generation and editing API client.
+    #
+    # @example
+    #   client = RunApi::HappyHorse::Client.new(api_key: "your-api-key")
+    #   result = client.text_to_video.run(
+    #     model: "happyhorse-text-to-video", prompt: "A horse galloping across a sunset beach"
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToVideo] Text-to-video generation with optional character consistency.
+      attr_reader :text_to_video
+      # @return [Resources::ImageToVideo] Image-to-video animation from a first-frame image.
+      attr_reader :image_to_video
+      # @return [Resources::EditVideo] Video editing with text prompts and reference images.
+      attr_reader :edit_video
 
       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)
         @image_to_video = Resources::ImageToVideo.new(http)
         @edit_video = Resources::EditVideo.new(http)

data/lib/runapi/happyhorse/contract_gen.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RunApi
+  module HappyHorse
+    CONTRACT = {
+      "edit-video" => {
+        "models" => ["happyhorse-edit-video"],
+        "fields_by_model" => {
+          "happyhorse-edit-video" => {
+            "audio_setting" => {
+              "enum" => ["auto", "original"]
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "seed" => {
+              "type" => "integer"
+            },
+            "source_video_url" => {
+              "required" => true
+            }
+          }
+        }
+      },
+      "image-to-video" => {
+        "models" => ["happyhorse-image-to-video"],
+        "fields_by_model" => {
+          "happyhorse-image-to-video" => {
+            "duration_seconds" => {
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          }
+        }
+      },
+      "text-to-video" => {
+        "models" => ["happyhorse-character", "happyhorse-text-to-video"],
+        "fields_by_model" => {
+          "happyhorse-character" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1", "4:3", "3:4"]
+            },
+            "duration_seconds" => {
+              "type" => "integer"
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "reference_image_urls" => {
+              "required" => true
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          },
+          "happyhorse-text-to-video" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1", "4:3", "3:4"]
+            },
+            "duration_seconds" => {
+              "type" => "integer"
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"]
+            },
+            "seed" => {
+              "type" => "integer"
+            }
+          }
+        }
+      }
+    }.freeze
+  end
+end

data/lib/runapi/happyhorse/resources/edit_video.rb

@@ -3,6 +3,8 @@
 module RunApi
   module HappyHorse
     module Resources
+      # HappyHorse edit-video resource.
+      # Transform an existing video with a text prompt and optional reference images.
       class EditVideo
         include RunApi::Core::ResourceHelpers
 
@@ -16,17 +18,29 @@ module RunApi
           @http = http
         end
 
+        # Create an edit-video task and wait until complete.
+        #
+        # @param params [Hash] edit-video parameters
+        # @return [RunApi::HappyHorse::Types::CompletedEditVideoResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create an edit-video task.
+        #
+        # @param params [Hash] edit-video parameters
+        # @return [RunApi::HappyHorse::Types::EditVideoResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get edit-video task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::HappyHorse::Types::EditVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -34,17 +48,15 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "model is required" unless param(params, :model) == Types::EDIT_VIDEO_MODEL
+          validate_contract!(CONTRACT["edit-video"], params)
+
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "source_video_url is required" unless param(params, :source_video_url)
 
           reference_image_urls = param(params, :reference_image_urls)
           if reference_image_urls && (!reference_image_urls.is_a?(Array) || !REFERENCE_IMAGE_RANGE.cover?(reference_image_urls.size))
             raise Core::ValidationError, "reference_image_urls must include at most #{REFERENCE_IMAGE_RANGE.max} entries"
           end
 
-          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
-          validate_optional!(params, :audio_setting, Types::AUDIO_SETTINGS)
           validate_integer_range!(params, :seed, Types::SEED_RANGE)
         end
 

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

@@ -3,6 +3,8 @@
 module RunApi
   module HappyHorse
     module Resources
+      # HappyHorse image-to-video resource.
+      # Animate a still first-frame image into video, guided by an optional text prompt.
       class ImageToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -15,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Create an image-to-video task and wait until complete.
+        #
+        # @param params [Hash] image-to-video parameters
+        # @return [RunApi::HappyHorse::Types::CompletedImageToVideoResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create an image-to-video task.
+        #
+        # @param params [Hash] image-to-video parameters
+        # @return [RunApi::HappyHorse::Types::ImageToVideoResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get image-to-video task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::HappyHorse::Types::ImageToVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -33,10 +47,8 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "model is required" unless param(params, :model) == Types::IMAGE_TO_VIDEO_MODEL
-          raise Core::ValidationError, "first_frame_image_url is required" unless param(params, :first_frame_image_url)
+          validate_contract!(CONTRACT["image-to-video"], params)
 
-          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
           validate_integer_range!(params, :duration_seconds, Types::DURATION_RANGE)
           validate_integer_range!(params, :seed, Types::SEED_RANGE)
         end

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

@@ -3,6 +3,8 @@
 module RunApi
   module HappyHorse
     module Resources
+      # HappyHorse text-to-video resource.
+      # Generate video from a text prompt, with optional character consistency via happyhorse-character.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -16,17 +18,29 @@ module RunApi
           @http = http
         end
 
+        # Create a text-to-video task and wait until complete.
+        #
+        # @param params [Hash] text-to-video parameters
+        # @return [RunApi::HappyHorse::Types::CompletedTextToVideoResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create a text-to-video task.
+        #
+        # @param params [Hash] text-to-video parameters
+        # @return [RunApi::HappyHorse::Types::TextToVideoResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get text-to-video task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::HappyHorse::Types::TextToVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -34,21 +48,19 @@ module RunApi
         private
 
         def validate_params!(params)
-          model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless Types::TEXT_TO_VIDEO_MODELS.include?(model)
+          validate_contract!(CONTRACT["text-to-video"], params)
+
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
 
           reference_image_urls = param(params, :reference_image_urls)
-          if model == Types::CHARACTER_MODEL
-            unless reference_image_urls.is_a?(Array) && REFERENCE_IMAGE_URLS_RANGE.cover?(reference_image_urls.size)
+          if param(params, :model) == Types::CHARACTER_MODEL
+            if reference_image_urls && !(reference_image_urls.is_a?(Array) && REFERENCE_IMAGE_URLS_RANGE.cover?(reference_image_urls.size))
               raise Core::ValidationError, "reference_image_urls must include between #{REFERENCE_IMAGE_URLS_RANGE.min} and #{REFERENCE_IMAGE_URLS_RANGE.max} entries"
             end
           elsif reference_image_urls
             raise Core::ValidationError, "reference_image_urls is only supported for #{Types::CHARACTER_MODEL}"
           end
 
-          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
-          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
           validate_integer_range!(params, :duration_seconds, Types::DURATION_RANGE)
           validate_integer_range!(params, :seed, Types::SEED_RANGE)
         end

data/lib/runapi/happyhorse/types.rb

@@ -2,18 +2,16 @@
 
 module RunApi
   module HappyHorse
+    # Type definitions and constants for HappyHorse video generation and editing.
     module Types
-      TEXT_TO_VIDEO_MODEL = "happyhorse-text-to-video"
+      # Character-consistent model; requires 1-9 reference_image_urls.
       CHARACTER_MODEL = "happyhorse-character"
-      TEXT_TO_VIDEO_MODELS = [TEXT_TO_VIDEO_MODEL, CHARACTER_MODEL].freeze
-      IMAGE_TO_VIDEO_MODEL = "happyhorse-image-to-video"
-      EDIT_VIDEO_MODEL = "happyhorse-edit-video"
-      OUTPUT_RESOLUTIONS = %w[720p 1080p].freeze
-      ASPECT_RATIOS = %w[16:9 9:16 1:1 4:3 3:4].freeze
-      AUDIO_SETTINGS = %w[auto original].freeze
+      # Duration range in seconds (3-15). Defaults to 5.
       DURATION_RANGE = (3..15)
+      # Reproducibility seed range.
       SEED_RANGE = (0..2_147_483_647)
 
+      # A generated video file with a download URL.
       class MediaUrl < RunApi::Core::BaseModel
         optional :url, String
       end
@@ -25,6 +23,8 @@ module RunApi
         optional :error, String
       end
 
+      # Narrowed response returned by +run()+ once polling observes +status: "completed"+.
+      # +videos+ is required so consumers never have to null-check it on a successful task.
       class CompletedTextToVideoResponse < TextToVideoResponse
         required :videos, [-> { MediaUrl }]
       end

data/lib/runapi/happyhorse.rb

@@ -2,6 +2,7 @@
 
 require "runapi/core"
 require_relative "happyhorse/types"
+require_relative "happyhorse/contract_gen"
 require_relative "happyhorse/resources/edit_video"
 require_relative "happyhorse/resources/image_to_video"
 require_relative "happyhorse/resources/text_to_video"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-happyhorse
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,17 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
-description: The happyhorse ai api Ruby SDK is the language-specific package for HappyHorse
-  on RunAPI. Use this package for text, image, and edit-video workflows that need
-  JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+        version: 0.2.7
+description: The HappyHorse Ruby SDK is the language-specific package for HappyHorse
+  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: []
@@ -38,6 +39,7 @@ files:
 - lib/runapi-happyhorse.rb
 - lib/runapi/happyhorse.rb
 - lib/runapi/happyhorse/client.rb
+- lib/runapi/happyhorse/contract_gen.rb
 - lib/runapi/happyhorse/resources/edit_video.rb
 - lib/runapi/happyhorse/resources/image_to_video.rb
 - lib/runapi/happyhorse/resources/text_to_video.rb
@@ -46,9 +48,11 @@ homepage: https://runapi.ai/models/happyhorse
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: happyhorse
   homepage_uri: https://runapi.ai/models/happyhorse
   documentation_uri: https://github.com/runapi-ai/happyhorse-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/happyhorse-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/happyhorse-sdk/issues
   changelog_uri: https://github.com/runapi-ai/happyhorse-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths: