runapi-runway 0.2.4 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 551a001340c6ffa42d01384ca7ea06226bbffa41c8cf61d73dd485ea68655ddb
-  data.tar.gz: 36e6813b94e61df19973e8f50081a43e23eb8f1662c5e33842a9f80df18115b2
+  metadata.gz: 59ad3e607d33dc4bb65bd09cbf86eaf3ff1de1c48c319db17a6ff01e28e506e1
+  data.tar.gz: bdb1f84d784e5edcb01566aafd8f82865c6b6cf2b2552464981c16d6e29745c5
 SHA512:
-  metadata.gz: 70fc8554e1b847497fa7d997024869c8b124b82b76dc9704fbe4e4ad9dc3c2f80d75e9452093df40b065d9b8188da4fedf9d0e297822336c9865688e0992fd29
-  data.tar.gz: 8dad4c58ee7e1bd07c2deacbb07db763031209f112ffa9f30cd14718725176c125fb8febd4d52f576c5afb6d1aeef8488f484bd37f72c2df980539524de91e32
+  metadata.gz: 0b0be7c1953ea69ff61be3c96c23fb5f615288da5d6e8f8b9f72e71eb748049c0eab3697dc9576c3549116ac9f1eae18fbc1662040c6097971b5289adb16efef
+  data.tar.gz: d88f0bf293488b0c5da4bd817578820525f8b7edb7a0ccffcb57044bb8f09030f6de5389fb2264108e1adcfd12d4f11d0ea9ae4e795dca7ea6f5a01cac75d91e

data/README.md

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

data/lib/runapi/runway/client.rb

@@ -2,14 +2,23 @@
 
 module RunApi
   module Runway
-    class Client
-      attr_reader :text_to_video, :extend_video
+    # Runway Gen-4 video generation API client.
+    #
+    # @example
+    #   client = RunApi::Runway::Client.new(api_key: "your-api-key")
+    #   result = client.text_to_video.run(
+    #     prompt: "A timelapse of a city skyline at sunset",
+    #     duration_seconds: 10,
+    #     output_resolution: "720p"
+    #   )
+    class Client < RunApi::Core::Client
+      # @return [Resources::TextToVideo] Text-to-video and image-to-video operations.
+      attr_reader :text_to_video
+      # @return [Resources::ExtendVideo] Extend-video operations.
+      attr_reader :extend_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)
       end

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

@@ -3,6 +3,8 @@
 module RunApi
   module Runway
     module Resources
+      # Runway extend-video resource.
+      # Append additional footage to a previously generated video, continuing from where the source task left off.
       class ExtendVideo
         include RunApi::Core::ResourceHelpers
 
@@ -14,17 +16,33 @@ module RunApi
           @http = http
         end
 
+        # Extend a video and wait until complete.
+        #
+        # @param source_task_id [String] ID of the completed TextToVideo or ExtendVideo task to continue from
+        # @param prompt [String] prompt describing the continuation footage
+        # @param output_resolution [String] must match the resolution of the source task ("720p" or "1080p")
+        # @param watermark [String, nil] watermark text burned into the output
+        # @param callback_url [String, nil] webhook URL for completion notification
+        # @return [RunApi::Runway::Types::CompletedTaskResponse] completed task with videos
         def run(**params)
           task = create(**params)
           poll_until_complete { get(task.id) }
         end
 
+        # Create an extend-video task without waiting for completion.
+        #
+        # @param params [Hash] extend-video parameters (see {#run} for details)
+        # @return [RunApi::Runway::Types::TaskCreateResponse] task creation result with id
         def create(**params)
           params = compact_params(params)
           validate_params!(params)
           request(:post, ENDPOINT, body: params)
         end
 
+        # Get extend-video task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::Runway::Types::TaskResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -32,11 +50,10 @@ module RunApi
         private
 
         def validate_params!(params)
-          raise Core::ValidationError, "task_id is required" unless param(params, :task_id)
+          raise Core::ValidationError, "source_task_id is required" unless param(params, :source_task_id)
           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, "quality is required" unless param(params, :quality)
-          validate_optional!(params, :quality, Types::QUALITIES)
+          raise Core::ValidationError, "output_resolution is required" unless param(params, :output_resolution)
+          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
         end
       end
     end

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

@@ -3,6 +3,8 @@
 module RunApi
   module Runway
     module Resources
+      # Runway text-to-video resource.
+      # Generate video from a text prompt, optionally using a first-frame image for image-to-video generation.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -14,17 +16,35 @@ module RunApi
           @http = http
         end
 
+        # Create a text-to-video task and wait until complete.
+        #
+        # @param prompt [String] video description prompt
+        # @param duration_seconds [Integer] video length: 5 or 10
+        # @param output_resolution [String] "720p" or "1080p"
+        # @param first_frame_image_url [String, nil] opening frame image URL for image-to-video
+        # @param aspect_ratio [String, nil] only for pure text-to-video (no first-frame image)
+        # @param watermark [String, nil] watermark text burned into the output
+        # @param callback_url [String, nil] webhook URL for completion notification
+        # @return [RunApi::Runway::Types::CompletedTaskResponse] 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 for completion.
+        #
+        # @param params [Hash] text-to-video parameters (see {#run} for details)
+        # @return [RunApi::Runway::Types::TaskCreateResponse] 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::Runway::Types::TaskResponse] current task status
         def get(id)
           request(:get, "#{ENDPOINT}/#{id}")
         end
@@ -33,9 +53,9 @@ module RunApi
 
         def validate_params!(params)
           raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          raise Core::ValidationError, "duration is required" unless param(params, :duration)
-          raise Core::ValidationError, "quality is required" unless param(params, :quality)
-          validate_optional!(params, :quality, Types::QUALITIES)
+          raise Core::ValidationError, "duration_seconds is required" unless param(params, :duration_seconds)
+          raise Core::ValidationError, "output_resolution is required" unless param(params, :output_resolution)
+          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
           validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
         end
       end

data/lib/runapi/runway/types.rb

@@ -2,28 +2,43 @@
 
 module RunApi
   module Runway
+    # Type definitions and constants for Runway Gen-4 video generation.
     module Types
-      QUALITIES = %w[720p 1080p].freeze
+      # Output resolution. 720p (1280x720) is faster and lower cost;
+      # 1080p (1920x1080) produces higher detail at higher cost.
+      OUTPUT_RESOLUTIONS = %w[720p 1080p].freeze
+
+      # Aspect ratio for pure text-to-video. Ignored when a first-frame image is provided.
       ASPECT_RATIOS = %w[16:9 9:16 1:1 4:3 3:4].freeze
 
+      # A generated video file with a download URL.
       class Video < RunApi::Core::BaseModel
         optional :id, String
         required :url, String
       end
 
+      # A generated image file with a download URL.
+      class Image < RunApi::Core::BaseModel
+        required :url, String
+      end
+
+      # Full task response returned by polling. Contains output media once the task completes.
       class TaskResponse < RunApi::Core::TaskResponse
         required :id, String
         optional :status, String, enum: -> { RunApi::Core::TaskResponse::Status::ALL }
-        optional :videos, [ -> { Video } ]
-        optional :image_url, String
-        optional :parent_task_id, String
+        optional :videos, [-> { Video }]
+        optional :images, [-> { Image }]
+        optional :source_task_id, String
         optional :error, String
       end
 
+      # Response returned when a task is first created, before polling begins.
       class TaskCreateResponse < TaskResponse; end
 
+      # Narrowed response returned by +run()+ once polling observes completion.
+      # +videos+ is guaranteed present so consumers never need to null-check.
       class CompletedTaskResponse < TaskResponse
-        required :videos, [ -> { Video } ]
+        required :videos, [-> { Video }]
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-runway
 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 Runway SDK for JavaScript, Ruby, and Go
+        version: 0.2.6
+description: The runway api Ruby SDK is the language-specific package for Runway on
+  RunAPI. Use this runway 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-runway.rb
 - lib/runapi/runway.rb
 - lib/runapi/runway/client.rb
@@ -42,7 +47,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models/runway
-  documentation_uri: https://github.com/runapi-ai/runway-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/runway-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/runway-sdk
   changelog_uri: https://github.com/runapi-ai/runway-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: Runway API SDKs for JavaScript, Ruby, and Go on RunAPI.
+summary: Runway API Ruby SDK for RunAPI
 test_files: []