runapi-hailuo 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b679c1414a1a46ad2fbfa006d6277454617ad6402f61cb910240162764fd145
-  data.tar.gz: 765933fe4869b085f8bbcf11e64fa473921e4e99b51a6f4c200365370772a2ea
+  metadata.gz: 9f95e54a3c54efd90d4dd44df70117de6da0b446167b2cf83c70640a1e7647a9
+  data.tar.gz: 4965df466901387f44480016ae970437fa4e90b7a81c14dcb680bac6403ede69
 SHA512:
-  metadata.gz: dc88531634f5fda08175d4c571132ff914c454a6de562196154a44f0b07b58159bc30c0dbe5a8988a6812f8d32b034a4da596a2d7bb68171d19903b5a695e6b3
-  data.tar.gz: cd890de40fd7cf2f26d5e47b68a6c869f238cb565967e0645a89bbba81b2abae1d82298d004b134296bbf6bf338dd55d6a7c152efd5fbb3d8365482abedab9f9
+  metadata.gz: c22c7bdf46bcb6458b1f0753a8c542101fa05a5f56de8080fbbc8d298d4da8f985196b064fc1340d113e3cc71feb10ef868ed53a95fba158b350f6d1ee11a20f
+  data.tar.gz: 9d94362787daf471cc98de37c2292bd93fee8836504c0d4e219b1d6d5a3d8e621a3c6b0d2fb5c6b285e21dd35b36f1a9eb8be5f599e44e7e100f143979dd8c60

data/README.md

@@ -0,0 +1,45 @@
+# Hailuo AI API Ruby SDK for RunAPI
+
+The hailuo ai api Ruby SDK is the language-specific package for Hailuo on RunAPI. Use this hailuo 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 hailuo ai api README is the Ruby package guide inside the public `hailuo-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/hailuo; for API reference, use https://runapi.ai/docs#hailuo; for SDK docs, use https://runapi.ai/docs#sdk-hailuo.
+
+## Install
+
+```bash
+gem install runapi-hailuo
+```
+
+## Quick start
+
+```ruby
+require "runapi-hailuo"
+
+client = RunApi::Hailuo::Client.new
+task = client.text_to_video.create(
+  # Pass the Hailuo JSON request body from https://runapi.ai/docs#hailuo.
+)
+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.
+
+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::Hailuo` error classes when building video jobs, Rails workers, or scripts. The available resources include text to videos, and image to videos. 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/hailuo
+- SDK docs: https://runapi.ai/docs#sdk-hailuo
+- Product docs: https://runapi.ai/docs#hailuo
+- Pricing and rate limits: https://runapi.ai/models/hailuo/02-text-to-video-pro
+- Provider comparison: https://runapi.ai/providers/minimax
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/hailuo-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/runapi/hailuo/client.rb

@@ -2,14 +2,22 @@
 
 module RunApi
   module Hailuo
-    class Client
-      attr_reader :text_to_video, :image_to_video
+    # Hailuo text-to-video and image-to-video generation API client.
+    #
+    # @example
+    #   client = RunApi::Hailuo::Client.new(api_key: "your-api-key")
+    #   result = client.text_to_video.run(
+    #     model: "hailuo-02-text-to-video-standard",
+    #     prompt: "A timelapse of cherry blossoms blooming in a Japanese garden"
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToVideo] Text-to-video generation operations.
+      attr_reader :text_to_video
+      # @return [Resources::ImageToVideo] Image-to-video generation operations.
+      attr_reader :image_to_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)

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

@@ -3,6 +3,8 @@
 module RunApi
   module Hailuo
     module Resources
+      # Hailuo image-to-video resource.
+      # Animate a still image into video guided by a text prompt and first-frame image.
       class ImageToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -15,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Generate an image-to-video task and wait until complete.
+        #
+        # @param params [Hash] image-to-video parameters
+        # @return [RunApi::Hailuo::Types::CompletedVideoTaskResponse] 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::Hailuo::Types::VideoTaskResponse] 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::Hailuo::Types::VideoTaskResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -36,35 +50,35 @@ module RunApi
           model = param(params, :model)
           raise Core::ValidationError, "model is required" unless Types::IMAGE_TO_VIDEO_MODELS.include?(model)
           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 = param(params, :duration)
-          resolution = param(params, :resolution)
+          duration_seconds = param(params, :duration_seconds)
+          output_resolution = param(params, :output_resolution)
 
-          if duration && !Types::DURATIONS.include?(duration.to_s)
-            raise Core::ValidationError, "duration must be one of: #{Types::DURATIONS.join(", ")}"
+          if duration_seconds && !Types::DURATIONS.include?(duration_seconds)
+            raise Core::ValidationError, "duration_seconds must be one of: #{Types::DURATIONS.join(", ")}"
           end
 
           case model
           when "hailuo-02-image-to-video-pro"
-            raise Core::ValidationError, "duration is not supported for #{model}" if duration
-            raise Core::ValidationError, "resolution is not supported for #{model}" if resolution
+            raise Core::ValidationError, "duration_seconds is not supported for #{model}" if duration_seconds
+            raise Core::ValidationError, "output_resolution is not supported for #{model}" if output_resolution
           when "hailuo-02-image-to-video-standard"
-            validate_resolution!(resolution, Types::IMAGE_02_RESOLUTIONS) if resolution
+            validate_output_resolution!(output_resolution, Types::IMAGE_02_RESOLUTIONS) if output_resolution
           else
-            validate_resolution!(resolution, Types::IMAGE_23_RESOLUTIONS) if resolution
-            raise Core::ValidationError, "end_image_url is not supported for #{model}" if param(params, :end_image_url)
+            validate_output_resolution!(output_resolution, Types::IMAGE_23_RESOLUTIONS) if output_resolution
+            raise Core::ValidationError, "last_frame_image_url is not supported for #{model}" if param(params, :last_frame_image_url)
             raise Core::ValidationError, "prompt_optimizer is not supported for #{model}" if param(params, :prompt_optimizer)
-            if duration.to_s == "10" && resolution.to_s == "1080P"
-              raise Core::ValidationError, "1080P does not support 10-second duration"
+            if duration_seconds == 10 && output_resolution.to_s == "1080p"
+              raise Core::ValidationError, "1080p does not support 10-second duration"
             end
           end
         end
 
-        def validate_resolution!(resolution, allowed)
-          return if allowed.include?(resolution.to_s)
+        def validate_output_resolution!(output_resolution, allowed)
+          return if allowed.include?(output_resolution.to_s)
 
-          raise Core::ValidationError, "resolution must be one of: #{allowed.join(", ")}"
+          raise Core::ValidationError, "output_resolution must be one of: #{allowed.join(", ")}"
         end
       end
     end

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

@@ -3,6 +3,8 @@
 module RunApi
   module Hailuo
     module Resources
+      # Hailuo text-to-video resource.
+      # Generate video from a text prompt.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -15,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Generate a text-to-video task and wait until complete.
+        #
+        # @param params [Hash] text-to-video parameters
+        # @return [RunApi::Hailuo::Types::CompletedVideoTaskResponse] 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::Hailuo::Types::VideoTaskResponse] 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::Hailuo::Types::VideoTaskResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -37,14 +51,14 @@ module RunApi
           raise Core::ValidationError, "model is required" unless Types::TEXT_TO_VIDEO_MODELS.include?(model)
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
 
-          duration = param(params, :duration)
-          return unless duration
+          duration_seconds = param(params, :duration_seconds)
+          return unless duration_seconds
 
-          unless Types::DURATIONS.include?(duration.to_s)
-            raise Core::ValidationError, "duration must be one of: #{Types::DURATIONS.join(", ")}"
+          unless Types::DURATIONS.include?(duration_seconds)
+            raise Core::ValidationError, "duration_seconds must be one of: #{Types::DURATIONS.join(", ")}"
           end
           if model == "hailuo-02-text-to-video-pro"
-            raise Core::ValidationError, "duration is not supported for #{model}"
+            raise Core::ValidationError, "duration_seconds is not supported for #{model}"
           end
         end
       end

data/lib/runapi/hailuo/types.rb

@@ -2,31 +2,47 @@
 
 module RunApi
   module Hailuo
+    # Type definitions and constants for Hailuo video generation.
     module Types
+      # Text-to-video model variants. Pro produces higher-fidelity output;
+      # Standard is faster with slightly lower quality. Prompts limited to 1500 characters.
       TEXT_TO_VIDEO_MODELS = %w[hailuo-02-text-to-video-pro hailuo-02-text-to-video-standard].freeze
+
+      # Image-to-video model variants spanning two generations.
+      # 02 models: last-frame image, prompt optimizer, 512p/768p, 1500-char prompts.
+      # 2.3 models: 768p/1080p output, 5000-char prompts, no last-frame or prompt optimizer.
       IMAGE_TO_VIDEO_MODELS = %w[
         hailuo-02-image-to-video-pro
         hailuo-02-image-to-video-standard
         hailuo-2.3-image-to-video-pro
         hailuo-2.3-image-to-video-standard
       ].freeze
-      DURATIONS = %w[6 10].freeze
-      IMAGE_02_RESOLUTIONS = %w[512P 768P].freeze
-      IMAGE_23_RESOLUTIONS = %w[768P 1080P].freeze
 
+      # Video duration options in seconds.
+      DURATIONS = [6, 10].freeze
+
+      # Output resolutions for 02 generation image-to-video models.
+      IMAGE_02_RESOLUTIONS = %w[512p 768p].freeze
+
+      # Output resolutions for 2.3 generation image-to-video models. 1080p is not available with 10-second duration.
+      IMAGE_23_RESOLUTIONS = %w[768p 1080p].freeze
+
+      # A generated video file with a download URL.
       class MediaUrl < RunApi::Core::BaseModel
         optional :url, String
       end
 
+      # Video generation task status and results. Poll until status reaches a terminal state.
       class VideoTaskResponse < RunApi::Core::TaskResponse
         required :id, String
         optional :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
-        optional :videos, [ -> { MediaUrl } ]
+        optional :videos, [-> { MediaUrl }]
         optional :error, String
       end
 
+      # Narrowed response returned after successful completion, guaranteeing videos is present.
       class CompletedVideoTaskResponse < VideoTaskResponse
-        required :videos, [ -> { MediaUrl } ]
+        required :videos, [-> { MediaUrl }]
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-hailuo
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 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 Hailuo SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: The hailuo ai api Ruby SDK is the language-specific package for Hailuo
+  on RunAPI. Use this hailuo 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-hailuo.rb
 - lib/runapi/hailuo.rb
 - lib/runapi/hailuo/client.rb
@@ -42,7 +47,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/hailuo
-  documentation_uri: https://github.com/runapi-ai/hailuo-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/hailuo-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/hailuo-sdk
   changelog_uri: https://github.com/runapi-ai/hailuo-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -61,5 +66,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Hailuo API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Hailuo AI API Ruby SDK for RunAPI
 test_files: []