runapi-veo-3.1 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 304c93ccbf6c01279040c323008db17aa2168d4d7e01c1a0582ef3bb348bf4ea
-  data.tar.gz: 293d5ac2cc0d180d94b3e7469731080b0f96b03613abe6f963b25035be95ab27
+  metadata.gz: 5fa5bd7f269c8b608d55c11f90a388aa2df67624283c864c4f4a79c43e703b1c
+  data.tar.gz: 853aa5135a16d6ab5766a9057ac8e7417dd7a29f808a88a1ca21149d50552f67
 SHA512:
-  metadata.gz: ce3a494d33a8289424abe5237c86699eafa66514017664f14e3aa4a087ef968d50e23de3a4b0df34e0fec0c92997d6b26c004f3196b07564a8aadafe9cb4bac7
-  data.tar.gz: 214f758deab6d00915cf7d97118ab2b9d5ee226de2f7e628651207d4a1ed3460de0f134eea122fc97707720ac437b83a779bb172c29e25d8f8ae359afd362029
+  metadata.gz: ddb090ed8af4a5e887c50f7061e89e9bbe76ce5757e7d21e870f086eb9e5038aa39dceb9744cfec01b639c2b258a6fd8fa9a074ef551b3e2aee8f959293312bc
+  data.tar.gz: 4624572eea7ce421e622d7d852bf5f08e14d8af862835c6c5cdd5372b61f445f9cda40218125620633fe4c1f6213f77b2faf9dc2e6ffbaaf6c3a2bcc5ea7ce35

data/README.md

@@ -24,6 +24,8 @@ status = client.generations.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::Veo3` error classes when building video jobs, Rails workers, or scripts. Text-to-video request bodies can include `duration` with `4`, `6`, or `8` seconds. The available resources include generations, extensions, hd1080p, and hd4k. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.

data/lib/runapi/veo_3_1/client.rb

@@ -9,17 +9,14 @@ module RunApi
     #   result = client.text_to_video.run(
     #     model: "veo-3.1-fast", prompt: "A drone shot over mountains at sunset"
     #   )
-    class Client
+    class Client < RunApi::Core::Client
       # @return [Resources::TextToVideo] Text, image, and reference-image operations.
       # @return [Resources::ExtendVideo] Video extension operations.
       # @return [Resources::UpscaleVideo] Video upscaling operations.
       attr_reader :text_to_video, :extend_video, :upscale_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)
         @extend_video = Resources::ExtendVideo.new(http)
         @upscale_video = Resources::UpscaleVideo.new(http)

data/lib/runapi/veo_3_1/resources/extend_video.rb

@@ -4,6 +4,7 @@ module RunApi
   module Veo31
     module Resources
       # Veo 3.1 video extension resource.
+      # Append additional footage to a completed text-to-video or extend-video task.
       class ExtendVideo
         include RunApi::Core::ResourceHelpers
 
@@ -16,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Extend a video and wait until complete.
+        #
+        # @param params [Hash] extend-video parameters (requires source_task_id and prompt)
+        # @return [RunApi::Veo31::Types::CompletedExtendVideoResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create a video extension task without waiting.
+        #
+        # @param params [Hash] extend-video parameters
+        # @return [RunApi::Veo31::Types::ExtendVideoResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get video extension task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::Veo31::Types::ExtendVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end

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

@@ -4,6 +4,7 @@ module RunApi
   module Veo31
     module Resources
       # Veo 3.1 text-to-video resource.
+      # Generate video from text, first/last frame images, or 1-3 reference images.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -16,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Generate a video and wait until complete.
+        #
+        # @param params [Hash] text-to-video parameters
+        # @return [RunApi::Veo31::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 without waiting.
+        #
+        # @param params [Hash] text-to-video parameters
+        # @return [RunApi::Veo31::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::Veo31::Types::TextToVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end

data/lib/runapi/veo_3_1/resources/upscale_video.rb

@@ -3,7 +3,8 @@
 module RunApi
   module Veo31
     module Resources
-      # Veo 3.1 videos upscaling resource.
+      # Veo 3.1 video upscaling resource.
+      # Increase resolution of a completed text-to-video or extend-video task to 1080p or 4K.
       class UpscaleVideo
         include RunApi::Core::ResourceHelpers
 
@@ -16,17 +17,29 @@ module RunApi
           @http = http
         end
 
+        # Upscale a video and wait until complete.
+        #
+        # @param params [Hash] upscale parameters (requires source_task_id and output_resolution)
+        # @return [RunApi::Veo31::Types::CompletedUpscaleVideoResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create a video upscale task without waiting.
+        #
+        # @param params [Hash] upscale parameters
+        # @return [RunApi::Veo31::Types::UpscaleVideoResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get video upscale task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::Veo31::Types::UpscaleVideoResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end

data/lib/runapi/veo_3_1/types.rb

@@ -2,19 +2,32 @@
 
 module RunApi
   module Veo31
+    # Type definitions and constants for Veo 3.1 video generation.
     module Types
+      # Model variants: veo-3.1 (full quality, higher fidelity) and veo-3.1-fast (low latency).
       MODELS = %w[veo-3.1 veo-3.1-fast].freeze
+
+      # Upscale target resolutions: 1080p (1920x1080) or 4k (3840x2160, higher detail and cost).
       OUTPUT_RESOLUTIONS = %w[1080p 4k].freeze
+
+      # Generation input modes: text (default), first_and_last_frames (frame images),
+      # or reference (1-3 reference images, fast model only, 16:9 only).
       INPUT_MODES = %w[text first_and_last_frames reference].freeze
+
+      # Video aspect ratios: 16:9 landscape, 9:16 portrait, auto (crop based on input dimensions).
       ASPECT_RATIOS = %w[16:9 9:16 auto].freeze
+
+      # Allowed video durations in seconds.
       DURATIONS = [4, 6, 8].freeze
 
+      # A generated video with its download URL and metadata.
       class Video < RunApi::Core::BaseModel
         optional :url, String
         optional :resolution, String
         optional :has_audio
       end
 
+      # An input source (original image or video) referenced by the task.
       class Source < RunApi::Core::BaseModel
         optional :url, String
       end
@@ -34,6 +47,7 @@ module RunApi
         optional :sources, [-> { Source }]
       end
 
+      # Upscale task response. Includes the source task reference and optional media identifiers.
       class UpscaleVideoResponse < AsyncTaskResponse
         optional :source_task_id, String
         optional :videos, [-> { Video }]
@@ -41,6 +55,9 @@ module RunApi
         optional :media_ids, [String]
       end
 
+      # Narrowed responses returned by +run()+ methods 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, [-> { Video }]
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-veo-3.1
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 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 veo api Ruby SDK is the language-specific package for Veo 3 on RunAPI.
   Use this veo 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