runapi-hailuo 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1230de918ea20384c9e57ac5a3747ee7ba265e84e54e84db406fe2c8cf6d896
-  data.tar.gz: ea5f47c1117700e8cb0fbf814a910557ac5b8b11e364efa7c991bcfe85eafdb9
+  metadata.gz: 9f95e54a3c54efd90d4dd44df70117de6da0b446167b2cf83c70640a1e7647a9
+  data.tar.gz: 4965df466901387f44480016ae970437fa4e90b7a81c14dcb680bac6403ede69
 SHA512:
-  metadata.gz: c868db7a59aecdaabbb57b1b2e3278930062ee6a015fc2384e13287a9a8e9127a876e7401a3419aec5d5739053de220476e0287ed0bb42f068c6456f344acdf5
-  data.tar.gz: d9752d9c75ebd3e679cfb119dc0aa7047dc5ff08631e97c135babed45b05f6f295f3b50422aa5a81fdf9782e697acce8b20b6602061db0562f3f8874c217c712
+  metadata.gz: c22c7bdf46bcb6458b1f0753a8c542101fa05a5f56de8080fbbc8d298d4da8f985196b064fc1340d113e3cc71feb10ef868ed53a95fba158b350f6d1ee11a20f
+  data.tar.gz: 9d94362787daf471cc98de37c2292bd93fee8836504c0d4e219b1d6d5a3d8e621a3c6b0d2fb5c6b285e21dd35b36f1a9eb8be5f599e44e7e100f143979dd8c60

data/README.md

@@ -24,6 +24,8 @@ 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.

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

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

data/lib/runapi/hailuo/types.rb

@@ -2,22 +2,37 @@
 
 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
+
+      # 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 }
@@ -25,6 +40,7 @@ module RunApi
         optional :error, String
       end
 
+      # Narrowed response returned after successful completion, guaranteeing videos is present.
       class CompletedVideoTaskResponse < VideoTaskResponse
         required :videos, [-> { MediaUrl }]
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-hailuo
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - RunAPI
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        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