runapi-veo-3.1 0.2.4 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c956acce113ea474bd15613081c7b4cdd3ffbb70959f78785a363c229f32886c
-  data.tar.gz: 57321ad7e796c37e3da66b43621bc4ccc5fb3e9f30ee58fa60ce728d5fc9afba
+  metadata.gz: 5fa5bd7f269c8b608d55c11f90a388aa2df67624283c864c4f4a79c43e703b1c
+  data.tar.gz: 853aa5135a16d6ab5766a9057ac8e7417dd7a29f808a88a1ca21149d50552f67
 SHA512:
-  metadata.gz: ca74a7c7b539f8e8fdf72471664641246e26e2bfd8c71299fc559dffe13603b2015e9da2117d9fe675ca378dce6469c85d3be3f00d464534561727e9f9397baa
-  data.tar.gz: 74803c738d9042e439a6b7cea97719304231b6fd4cdb522117bbdc58b2ff6b932b9462a0a9706d97d152f35c547e3b7c7cbb4837f6ec63083d85f05fcbb72137
+  metadata.gz: ddb090ed8af4a5e887c50f7061e89e9bbe76ce5757e7d21e870f086eb9e5038aa39dceb9744cfec01b639c2b258a6fd8fa9a074ef551b3e2aee8f959293312bc
+  data.tar.gz: 4624572eea7ce421e622d7d852bf5f08e14d8af862835c6c5cdd5372b61f445f9cda40218125620633fe4c1f6213f77b2faf9dc2e6ffbaaf6c3a2bcc5ea7ce35

data/README.md

@@ -0,0 +1,45 @@
+# Veo API Ruby SDK for RunAPI
+
+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 RunAPI errors in Ruby.
+
+This veo api README is the Ruby package guide inside the public `veo3-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/veo-3.1; for API reference, use https://runapi.ai/docs#veo-3.1; for SDK docs, use https://runapi.ai/docs#sdk-veo-3.1.
+
+## Install
+
+```bash
+gem install runapi-veo3
+```
+
+## Quick start
+
+```ruby
+require "runapi-veo3"
+
+client = RunApi::Veo3::Client.new
+task = client.generations.create(
+  # Pass the Veo 3 JSON request body from https://runapi.ai/docs#veo-3.1.
+)
+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.
+
+## Links
+
+- Model page: https://runapi.ai/models/veo-3.1
+- SDK docs: https://runapi.ai/docs#sdk-veo-3.1
+- Product docs: https://runapi.ai/docs#veo-3.1
+- Pricing and rate limits: https://runapi.ai/models/veo-3.1/veo-3.1
+- Provider comparison: https://runapi.ai/providers/google
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/veo3-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

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
-      # @return [Resources::TextToVideo] Text, image, and reference-to-video operations.
+    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
@@ -34,7 +47,7 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "task_id is required" unless params[:task_id] || params["task_id"]
+          raise Core::ValidationError, "source_task_id is required" unless params[:source_task_id] || params["source_task_id"]
           raise Core::ValidationError, "prompt is required" unless params[:prompt] || params["prompt"]
         end
       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
@@ -43,38 +56,61 @@ module RunApi
           end
 
           validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
-          validate_optional!(params, :generation_type, Types::GENERATION_TYPES)
+          validate_optional!(params, :input_mode, Types::INPUT_MODES)
+          validate_duration!(params)
 
-          validate_generation_type!(params)
+          validate_input_mode!(params)
         end
 
-        def validate_generation_type!(params)
-          gen_type = param(params, :generation_type)
-          return unless gen_type
+        def validate_duration!(params)
+          duration_seconds = param(params, :duration_seconds)
+          return unless duration_seconds
+          return if Types::DURATIONS.include?(duration_seconds)
 
-          case gen_type
-          when "FIRST_AND_LAST_FRAMES_2_VIDEO"
-            urls = param(params, :image_urls)
-            raise Core::ValidationError, "image_urls is required for FIRST_AND_LAST_FRAMES_2_VIDEO" unless urls
-            unless urls.is_a?(Array) && urls.length.between?(1, 2)
-              raise Core::ValidationError, "image_urls must contain 1-2 items for FIRST_AND_LAST_FRAMES_2_VIDEO"
+          raise Core::ValidationError, "Invalid duration_seconds: #{duration_seconds}. Must be one of: #{Types::DURATIONS.join(", ")}"
+        end
+
+        def validate_input_mode!(params)
+          input_mode = param(params, :input_mode)
+          return unless input_mode
+
+          case input_mode
+          when "first_and_last_frames"
+            raise Core::ValidationError, "first_frame_image_url is required for first_and_last_frames" unless field_present?(params, :first_frame_image_url)
+            if field_present?(params, :reference_image_urls)
+              raise Core::ValidationError, "reference_image_urls requires input_mode reference"
             end
-          when "REFERENCE_2_VIDEO"
-            urls = param(params, :image_urls)
-            raise Core::ValidationError, "image_urls is required for REFERENCE_2_VIDEO" unless urls
+          when "reference"
+            urls = param(params, :reference_image_urls)
+            raise Core::ValidationError, "reference_image_urls is required for reference" unless urls
             unless urls.is_a?(Array) && urls.length.between?(1, 3)
-              raise Core::ValidationError, "image_urls must contain 1-3 items for REFERENCE_2_VIDEO"
+              raise Core::ValidationError, "reference_image_urls must contain 1-3 items for reference"
             end
             model = param(params, :model)
             unless model == "veo-3.1-fast"
-              raise Core::ValidationError, "REFERENCE_2_VIDEO requires model veo-3.1-fast"
+              raise Core::ValidationError, "reference requires model veo-3.1-fast"
             end
             ar = param(params, :aspect_ratio)
             if ar && ar != "16:9"
-              raise Core::ValidationError, "REFERENCE_2_VIDEO requires aspect_ratio 16:9"
+              raise Core::ValidationError, "reference requires aspect_ratio 16:9"
+            end
+            if field_present?(params, :first_frame_image_url) || field_present?(params, :last_frame_image_url)
+              raise Core::ValidationError, "first_frame_image_url and last_frame_image_url require input_mode first_and_last_frames"
+            end
+          else
+            if field_present?(params, :first_frame_image_url) || field_present?(params, :last_frame_image_url)
+              raise Core::ValidationError, "first_frame_image_url and last_frame_image_url require input_mode first_and_last_frames"
+            end
+            if field_present?(params, :reference_image_urls)
+              raise Core::ValidationError, "reference_image_urls requires input_mode reference"
             end
           end
         end
+
+        def field_present?(params, key)
+          value = param(params, key)
+          value.is_a?(Array) ? value.any? : !value.nil? && !value.to_s.empty?
+        end
       end
     end
   end

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

@@ -4,6 +4,7 @@ module RunApi
   module Veo31
     module Resources
       # 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
@@ -34,10 +47,10 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "task_id is required" unless params[:task_id] || params["task_id"]
-          resolution = params[:target_resolution] || params["target_resolution"]
-          unless Types::TARGET_RESOLUTIONS.include?(resolution)
-            raise Core::ValidationError, "target_resolution must be one of: #{Types::TARGET_RESOLUTIONS.join(", ")}"
+          raise Core::ValidationError, "source_task_id is required" unless params[:source_task_id] || params["source_task_id"]
+          output_resolution = params[:output_resolution] || params["output_resolution"]
+          unless Types::OUTPUT_RESOLUTIONS.include?(output_resolution)
+            raise Core::ValidationError, "output_resolution must be one of: #{Types::OUTPUT_RESOLUTIONS.join(", ")}"
           end
         end
       end

data/lib/runapi/veo_3_1/types.rb

@@ -2,47 +2,72 @@
 
 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
-      TARGET_RESOLUTIONS = %w[1080p 4k].freeze
-      GENERATION_TYPES = %w[TEXT_2_VIDEO FIRST_AND_LAST_FRAMES_2_VIDEO REFERENCE_2_VIDEO].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
+
       class AsyncTaskResponse < RunApi::Core::TaskResponse
         required :id, String
         optional :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
       end
 
       class TextToVideoResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
-        optional :video, -> { Video }
+        optional :videos, [-> { Video }]
+        optional :sources, [-> { Source }]
       end
 
       class ExtendVideoResponse < AsyncTaskResponse
-        optional :videos, [ -> { Video } ]
-        optional :video, -> { Video }
+        optional :videos, [-> { Video }]
+        optional :sources, [-> { Source }]
       end
 
+      # Upscale task response. Includes the source task reference and optional media identifiers.
       class UpscaleVideoResponse < AsyncTaskResponse
-        optional :video, -> { Video }
+        optional :source_task_id, String
+        optional :videos, [-> { Video }]
+        optional :sources, [-> { Source }]
+        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 } ]
+        required :videos, [-> { Video }]
       end
 
       class CompletedExtendVideoResponse < ExtendVideoResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
 
       class CompletedUpscaleVideoResponse < UpscaleVideoResponse
-        required :video, -> { Video }
+        required :videos, [-> { Video }]
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-veo-3.1
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.7
 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 Veo 3 SDK for JavaScript, Ruby, and Go
+        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
+  RunAPI errors in Ruby.
 email:
 - contact@runapi.ai
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
+- README.md
 - lib/runapi-veo_3_1.rb
 - lib/runapi/veo_3_1.rb
 - lib/runapi/veo_3_1/client.rb
@@ -43,7 +48,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/veo-3.1
-  documentation_uri: https://github.com/runapi-ai/veo-3.1-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/veo-3.1-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/veo-3.1-sdk
   changelog_uri: https://github.com/runapi-ai/veo-3.1-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
@@ -62,5 +67,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Veo 3 API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Veo API Ruby SDK for RunAPI
 test_files: []