runapi-hailuo 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1230de918ea20384c9e57ac5a3747ee7ba265e84e54e84db406fe2c8cf6d896
-  data.tar.gz: ea5f47c1117700e8cb0fbf814a910557ac5b8b11e364efa7c991bcfe85eafdb9
+  metadata.gz: 50152f6fb9b5ca8acd27bf0fcd7054b1a72974fa2211362e24a74cf59d871106
+  data.tar.gz: cee31f624d2d980f71d7e3a6b1bbcca4f6e3c5c33e02605a9432317d2e2a70e8
 SHA512:
-  metadata.gz: c868db7a59aecdaabbb57b1b2e3278930062ee6a015fc2384e13287a9a8e9127a876e7401a3419aec5d5739053de220476e0287ed0bb42f068c6456f344acdf5
-  data.tar.gz: d9752d9c75ebd3e679cfb119dc0aa7047dc5ff08631e97c135babed45b05f6f295f3b50422aa5a81fdf9782e697acce8b20b6602061db0562f3f8874c217c712
+  metadata.gz: 34ca581e88fd2d260db1fe43e0149c90d53c7f33c9fe53e59b58908a2bf7166f98c2e0e6635fa641c7ebd05b22a216d824a9690a921146a3ba9956e8946e0fd9
+  data.tar.gz: 7f0ba801df266b32043dae6f43d2dfa7180c18807f03037c91ea65a9f49e731c1d718ce17269611e4c906c5c3e944af0507c311279a0e086e126cbb1aa1f7844

data/README.md

@@ -1,8 +1,8 @@
-# Hailuo AI API Ruby SDK for RunAPI
+# Hailuo 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.
+The Hailuo Ruby SDK is the language-specific package for Hailuo 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.
 
-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.
+This 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
 
@@ -24,9 +24,11 @@ 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.
+Use Ruby keyword arguments and the `RunApi::Hailuo` error classes when building video jobs, Rails workers, or scripts. The available resources are `text_to_video` and `image_to_video`. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
 
 ## Links
 

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/contract_gen.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Hailuo
+    CONTRACT = {
+      "image-to-video" => {
+        "models" => ["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"],
+        "fields_by_model" => {
+          "hailuo-02-image-to-video-pro" => {
+            "duration_seconds" => {
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            }
+          },
+          "hailuo-02-image-to-video-standard" => {
+            "duration_seconds" => {
+              "enum" => [6, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["512p", "768p"]
+            }
+          },
+          "hailuo-2.3-image-to-video-pro" => {
+            "duration_seconds" => {
+              "enum" => [6, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["768p", "1080p"]
+            }
+          },
+          "hailuo-2.3-image-to-video-standard" => {
+            "duration_seconds" => {
+              "enum" => [6, 10],
+              "type" => "integer"
+            },
+            "first_frame_image_url" => {
+              "required" => true
+            },
+            "output_resolution" => {
+              "enum" => ["768p", "1080p"]
+            }
+          }
+        }
+      },
+      "text-to-video" => {
+        "models" => ["hailuo-02-text-to-video-pro", "hailuo-02-text-to-video-standard"],
+        "fields_by_model" => {
+          "hailuo-02-text-to-video-pro" => {
+            "duration_seconds" => {
+              "type" => "integer"
+            }
+          },
+          "hailuo-02-text-to-video-standard" => {
+            "duration_seconds" => {
+              "enum" => [6, 10],
+              "type" => "integer"
+            }
+          }
+        }
+      }
+    }.freeze
+  end
+end

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
@@ -33,26 +47,19 @@ module RunApi
         private
 
         def validate_params!(params)
-          model = param(params, :model)
-          raise Core::ValidationError, "model is required" unless Types::IMAGE_TO_VIDEO_MODELS.include?(model)
+          validate_contract!(CONTRACT["image-to-video"], params)
+
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "first_frame_image_url is required" unless param(params, :first_frame_image_url)
 
+          model = param(params, :model)
           duration_seconds = param(params, :duration_seconds)
           output_resolution = param(params, :output_resolution)
 
-          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_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_output_resolution!(output_resolution, Types::IMAGE_02_RESOLUTIONS) if output_resolution
-          else
-            validate_output_resolution!(output_resolution, Types::IMAGE_23_RESOLUTIONS) if output_resolution
+          when "hailuo-2.3-image-to-video-pro", "hailuo-2.3-image-to-video-standard"
             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_seconds == 10 && output_resolution.to_s == "1080p"
@@ -60,12 +67,6 @@ module RunApi
             end
           end
         end
-
-        def validate_output_resolution!(output_resolution, allowed)
-          return if allowed.include?(output_resolution.to_s)
-
-          raise Core::ValidationError, "output_resolution must be one of: #{allowed.join(", ")}"
-        end
       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
@@ -33,17 +47,12 @@ 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)
-          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
+          validate_contract!(CONTRACT["text-to-video"], params)
 
-          duration_seconds = param(params, :duration_seconds)
-          return unless duration_seconds
+          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
 
-          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"
+          model = param(params, :model)
+          if model == "hailuo-02-text-to-video-pro" && param(params, :duration_seconds)
             raise Core::ValidationError, "duration_seconds is not supported for #{model}"
           end
         end

data/lib/runapi/hailuo/types.rb

@@ -2,22 +2,14 @@
 
 module RunApi
   module Hailuo
+    # Type definitions and constants for Hailuo video generation.
     module Types
-      TEXT_TO_VIDEO_MODELS = %w[hailuo-02-text-to-video-pro hailuo-02-text-to-video-standard].freeze
-      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 = [6, 10].freeze
-      IMAGE_02_RESOLUTIONS = %w[512p 768p].freeze
-      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 +17,7 @@ module RunApi
         optional :error, String
       end
 
+      # Narrowed response returned after successful completion, guaranteeing videos is present.
       class CompletedVideoTaskResponse < VideoTaskResponse
         required :videos, [-> { MediaUrl }]
       end

data/lib/runapi/hailuo.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-hailuo
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +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 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.
+        version: 0.2.7
+description: The Hailuo Ruby SDK is the language-specific package for Hailuo 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: []
@@ -39,6 +39,7 @@ files:
 - lib/runapi-hailuo.rb
 - lib/runapi/hailuo.rb
 - lib/runapi/hailuo/client.rb
+- lib/runapi/hailuo/contract_gen.rb
 - lib/runapi/hailuo/resources/image_to_video.rb
 - lib/runapi/hailuo/resources/text_to_video.rb
 - lib/runapi/hailuo/types.rb
@@ -46,9 +47,11 @@ homepage: https://runapi.ai/models/hailuo
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: hailuo
   homepage_uri: https://runapi.ai/models/hailuo
   documentation_uri: https://github.com/runapi-ai/hailuo-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/hailuo-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/hailuo-sdk/issues
   changelog_uri: https://github.com/runapi-ai/hailuo-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -66,5 +69,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Hailuo AI API Ruby SDK for RunAPI
+summary: Hailuo API Ruby SDK for RunAPI
 test_files: []