runapi-happyhorse 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0fbd41ba815c6b83de99cd5c32f46981293c448a0e10fa9d5894403f26868f
-  data.tar.gz: 1b8ed70e59a12339fc45ead0a013cd78d1f3c52eb638faa90d750dcdab603ae4
+  metadata.gz: 8420f63d7f99ed90385490503c24de7fcb1057aafe9c7d2e707e0509df9daeb2
+  data.tar.gz: 76648efbe65479f2c4c042ae4e5d11b2fc51e8f76c0fe113836f784e797c4f98
 SHA512:
-  metadata.gz: 8b4b0986bf2e5c8ac7c1f7488c84237cb85933397a2af5760a254fb845b958a8b6a5b65d3f7353fb3680b35fb1aa0a4f628177423dfc2eb5077c12ca84b975b1
-  data.tar.gz: 45314c2e79d8f9ff6bee7e53811580dd2654aa94d0d4f80a4fabae768c58bcc7a28ddb3f145293bb20d2c8300f5e026fd70ff696549998109f3a955403bc0277
+  metadata.gz: f7e08714a1d7b8ffb5f22ac49c0d652876eeedff7c8e0a460cb9114db6604d9a98c275cb56d8244b46a0602891f62bf2ab9af652afa824476de778dc9ef6acbf
+  data.tar.gz: fefb8e30365b1d577314ef2de5dcda68bce75f85125fd0734128a5f648f255a5f2a3bdd26fc1078d637631662265ce7ab49ed197deb071cc1cfbbe5b6411c701

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, reference-to-video, and edit-video workflows that need JSON request bodies, task status lookup, and consistent RunAPI errors in Ruby.
+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.
 
 ## Install
 
@@ -15,15 +15,18 @@ require "runapi-happyhorse"
 
 client = RunApi::HappyHorse::Client.new
 video = client.text_to_video.run(
-  model: "happyhorse-text-to-video",
-  prompt: "A tiny paper horse gallops through a miniature cardboard city at night.",
-  resolution: "1080p",
+  model: "happyhorse-character",
+  prompt: "Character1 walks through a miniature cardboard city at night.",
+  reference_image_urls: ["https://cdn.runapi.ai/public/samples/reference-1.jpg"],
+  output_resolution: "1080p",
   aspect_ratio: "16:9",
-  duration: 5
+  duration_seconds: 5
 )
 ```
 
-For image-to-video, call `client.image_to_video.run` with `model: "happyhorse-image-to-video"` and exactly one `image_urls` entry. For reference-to-video, call `client.reference_to_video.run` with `model: "happyhorse-reference-to-video"` and 1-9 `reference_image` entries. For edit-video, call `client.edit_video.run` with `model: "happyhorse-video-edit"`, one `video_url`, and optional `reference_image` entries.
+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
 
@@ -31,8 +34,8 @@ For image-to-video, call `client.image_to_video.run` with `model: "happyhorse-im
 - SDK docs: https://runapi.ai/docs#sdk-happyhorse
 - Product docs: https://runapi.ai/docs#happyhorse
 - Image-to-video pricing and rate limits: https://runapi.ai/models/happyhorse/image-to-video
-- Reference-to-video pricing and rate limits: https://runapi.ai/models/happyhorse/reference-to-video
-- Edit-video pricing and rate limits: https://runapi.ai/models/happyhorse/video-edit
+- Character pricing and rate limits: https://runapi.ai/models/happyhorse/character
+- Edit-video pricing and rate limits: https://runapi.ai/models/happyhorse/edit-video
 - Pricing and rate limits: https://runapi.ai/models/happyhorse/text-to-video
 - Provider comparison: https://runapi.ai/providers/alibaba
 - Full catalog: https://runapi.ai/models

data/lib/runapi/happyhorse/client.rb

@@ -2,17 +2,25 @@
 
 module RunApi
   module HappyHorse
-    class Client
-      attr_reader :text_to_video, :image_to_video, :reference_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)
-        @reference_to_video = Resources::ReferenceToVideo.new(http)
         @edit_video = Resources::EditVideo.new(http)
       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
@@ -36,14 +50,14 @@ module RunApi
         def validate_params!(params)
           raise Core::ValidationError, "model is required" unless param(params, :model) == Types::EDIT_VIDEO_MODEL
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "video_url is required" unless param(params, :video_url)
+          raise Core::ValidationError, "source_video_url is required" unless param(params, :source_video_url)
 
-          reference_image = param(params, :reference_image)
-          if reference_image && (!reference_image.is_a?(Array) || !REFERENCE_IMAGE_RANGE.cover?(reference_image.size))
-            raise Core::ValidationError, "reference_image must include at most #{REFERENCE_IMAGE_RANGE.max} entries"
+          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, :resolution, Types::RESOLUTIONS)
+          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
@@ -52,8 +66,7 @@ module RunApi
           value = param(params, key)
           return unless value
 
-          integer = Integer(value, exception: false)
-          return if integer && range.cover?(integer)
+          return if value.is_a?(Integer) && range.cover?(value)
 
           raise Core::ValidationError, "#{key} must be an integer between #{range.min} and #{range.max}"
         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
 
@@ -10,23 +12,34 @@ module RunApi
 
         RESPONSE_CLASS = Types::ImageToVideoResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedImageToVideoResponse
-        IMAGE_URLS_MAX = 1
 
         def initialize(http)
           @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
@@ -35,13 +48,10 @@ module RunApi
 
         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)
 
-          image_urls = param(params, :image_urls)
-          raise Core::ValidationError, "image_urls is required" unless image_urls.is_a?(Array) && image_urls.any?
-          raise Core::ValidationError, "image_urls supports at most #{IMAGE_URLS_MAX} entry" if image_urls.size > IMAGE_URLS_MAX
-
-          validate_optional!(params, :resolution, Types::RESOLUTIONS)
-          validate_integer_range!(params, :duration, Types::DURATION_RANGE)
+          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
 
@@ -49,8 +59,7 @@ module RunApi
           value = param(params, key)
           return unless value
 
-          integer = Integer(value, exception: false)
-          return if integer && range.cover?(integer)
+          return if value.is_a?(Integer) && range.cover?(value)
 
           raise Core::ValidationError, "#{key} must be an integer between #{range.min} and #{range.max}"
         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
 
@@ -10,22 +12,35 @@ module RunApi
 
         RESPONSE_CLASS = Types::TextToVideoResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTextToVideoResponse
+        REFERENCE_IMAGE_URLS_RANGE = (1..9)
 
         def initialize(http)
           @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
@@ -33,12 +48,22 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "model is required" unless param(params, :model) == Types::TEXT_TO_VIDEO_MODEL
+          model = param(params, :model)
+          raise Core::ValidationError, "model is required" unless Types::TEXT_TO_VIDEO_MODELS.include?(model)
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
 
-          validate_optional!(params, :resolution, Types::RESOLUTIONS)
+          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)
+              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, Types::DURATION_RANGE)
+          validate_integer_range!(params, :duration_seconds, Types::DURATION_RANGE)
           validate_integer_range!(params, :seed, Types::SEED_RANGE)
         end
 
@@ -46,8 +71,7 @@ module RunApi
           value = param(params, key)
           return unless value
 
-          integer = Integer(value, exception: false)
-          return if integer && range.cover?(integer)
+          return if value.is_a?(Integer) && range.cover?(value)
 
           raise Core::ValidationError, "#{key} must be an integer between #{range.min} and #{range.max}"
         end

data/lib/runapi/happyhorse/types.rb

@@ -2,17 +2,28 @@
 
 module RunApi
   module HappyHorse
+    # Type definitions and constants for HappyHorse video generation and editing.
     module Types
+      # Standard text-to-video model.
       TEXT_TO_VIDEO_MODEL = "happyhorse-text-to-video"
+      # Character-consistent model; requires 1-9 reference_image_urls.
+      CHARACTER_MODEL = "happyhorse-character"
+      # All text-to-video model variants.
+      TEXT_TO_VIDEO_MODELS = [TEXT_TO_VIDEO_MODEL, CHARACTER_MODEL].freeze
       IMAGE_TO_VIDEO_MODEL = "happyhorse-image-to-video"
-      REFERENCE_TO_VIDEO_MODEL = "happyhorse-reference-to-video"
-      EDIT_VIDEO_MODEL = "happyhorse-video-edit"
-      RESOLUTIONS = %w[720p 1080p].freeze
+      EDIT_VIDEO_MODEL = "happyhorse-edit-video"
+      # Output resolution options. Defaults to 1080p.
+      OUTPUT_RESOLUTIONS = %w[720p 1080p].freeze
+      # Aspect ratio options. Defaults to 16:9.
       ASPECT_RATIOS = %w[16:9 9:16 1:1 4:3 3:4].freeze
-      AUDIO_SETTINGS = %w[auto origin].freeze
+      # Audio handling for video editing: "auto" lets the model decide, "original" preserves source audio.
+      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
@@ -24,14 +35,14 @@ 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
 
       ImageToVideoResponse = TextToVideoResponse
       CompletedImageToVideoResponse = CompletedTextToVideoResponse
-      ReferenceToVideoResponse = TextToVideoResponse
-      CompletedReferenceToVideoResponse = CompletedTextToVideoResponse
       EditVideoResponse = TextToVideoResponse
       CompletedEditVideoResponse = CompletedTextToVideoResponse
     end

data/lib/runapi/happyhorse.rb

@@ -4,7 +4,6 @@ require "runapi/core"
 require_relative "happyhorse/types"
 require_relative "happyhorse/resources/edit_video"
 require_relative "happyhorse/resources/image_to_video"
-require_relative "happyhorse/resources/reference_to_video"
 require_relative "happyhorse/resources/text_to_video"
 require_relative "happyhorse/client"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-happyhorse
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +15,17 @@ 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
+        version: 0.2.6
 description: The happyhorse ai api Ruby SDK is the language-specific package for HappyHorse
-  on RunAPI. Use this package for text, image, reference-to-video, and edit-video
-  workflows that need JSON request bodies, task status lookup, and consistent RunAPI
-  errors in Ruby.
+  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.
 email:
 - contact@runapi.ai
 executables: []
@@ -41,7 +40,6 @@ files:
 - lib/runapi/happyhorse/client.rb
 - lib/runapi/happyhorse/resources/edit_video.rb
 - lib/runapi/happyhorse/resources/image_to_video.rb
-- lib/runapi/happyhorse/resources/reference_to_video.rb
 - lib/runapi/happyhorse/resources/text_to_video.rb
 - lib/runapi/happyhorse/types.rb
 homepage: https://runapi.ai/models/happyhorse

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

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module RunApi
-  module HappyHorse
-    module Resources
-      class ReferenceToVideo
-        include RunApi::Core::ResourceHelpers
-
-        ENDPOINT = "/api/v1/happyhorse/reference_to_video"
-
-        RESPONSE_CLASS = Types::ReferenceToVideoResponse
-        COMPLETED_RESPONSE_CLASS = Types::CompletedReferenceToVideoResponse
-        REFERENCE_IMAGE_RANGE = (1..9)
-
-        def initialize(http)
-          @http = http
-        end
-
-        def run(**params)
-          task = create(**params)
-          poll_until_complete { get(task.id) }
-        end
-
-        def create(**params)
-          params = compact_params(params)
-          validate_params!(params)
-          request(:post, ENDPOINT, body: params)
-        end
-
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
-        end
-
-        private
-
-        def validate_params!(params)
-          raise Core::ValidationError, "model is required" unless param(params, :model) == Types::REFERENCE_TO_VIDEO_MODEL
-          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-
-          reference_image = param(params, :reference_image)
-          unless reference_image.is_a?(Array) && REFERENCE_IMAGE_RANGE.cover?(reference_image.size)
-            raise Core::ValidationError, "reference_image must include between #{REFERENCE_IMAGE_RANGE.min} and #{REFERENCE_IMAGE_RANGE.max} entries"
-          end
-
-          validate_optional!(params, :resolution, Types::RESOLUTIONS)
-          validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
-          validate_integer_range!(params, :duration, Types::DURATION_RANGE)
-          validate_integer_range!(params, :seed, Types::SEED_RANGE)
-        end
-
-        def validate_integer_range!(params, key, range)
-          value = param(params, key)
-          return unless value
-
-          integer = Integer(value, exception: false)
-          return if integer && range.cover?(integer)
-
-          raise Core::ValidationError, "#{key} must be an integer between #{range.min} and #{range.max}"
-        end
-      end
-    end
-  end
-end