runapi-runway 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 136d7bef7e251f84697d1faec9be01a6771a3948f4c2df29711f8c5d335c2e42
-  data.tar.gz: 76c88350d5408ce93c05ddb25e49e90429c5e5e76f540d8993eb3738ab5c2c94
+  metadata.gz: ad79cfb3fe2fd25106c5b06257c8f4a204bc2f423fa033cf7fd7c37af6aaf5a0
+  data.tar.gz: 0ea01d23599ba93b73cca5b682fceeb2d40c27d258f0c2c245f937dfbd5d4fff
 SHA512:
-  metadata.gz: c850f59712359438aa95bd65cebfcd3149f2f5b80d45378978f2b7a47b0190b308e12b220a4329ffd88535da128080e40d4eb43faa45a890e9431c43d6a782a0
-  data.tar.gz: adba718ecc15852b75fef465d757c9e6e6b922f68b5a2c91c4f83cb4b3fbeb517aa7718d3e25067c4abff473e5e38241647a0568f50c9165a9fc9384d9fc7f0d
+  metadata.gz: 4d452b908a3800518ccc32c8d9a300b24f8e47afd51f597d3703e1da2af01f899195437ad8483807825253b0970f3d67acd8da850674fb0c43f927f7d5a0f780
+  data.tar.gz: c8d1792c8e980bfe52f58c9fac6cfc4f8ce397bdae4abb31eebcd2cc74100574ed30f1311e8fc3f054f3481ad0605b0ec7cbd1bc00782a503c893b601decb521

data/README.md

@@ -1,8 +1,8 @@
-# Runway API Ruby SDK for RunAPI
+# Runway 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.
+The Runway Ruby SDK is the language-specific package for Runway 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 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.
+This 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
 
@@ -13,7 +13,7 @@ gem install runapi-runway
 ## Quick start
 
 ```ruby
-require "runapi-runway"
+require "runapi/runway"
 
 client = RunApi::Runway::Client.new
 task = client.text_to_video.create(
@@ -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::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.

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Runway
+    CONTRACT = {
+      "extend-video" => {
+        "models" => ["runway"],
+        "fields_by_model" => {
+          "runway" => {
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"],
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            },
+            "source_task_id" => {
+              "required" => true
+            }
+          }
+        }
+      },
+      "text-to-video" => {
+        "models" => ["runway"],
+        "fields_by_model" => {
+          "runway" => {
+            "aspect_ratio" => {
+              "enum" => ["16:9", "9:16", "1:1", "4:3", "3:4"]
+            },
+            "duration_seconds" => {
+              "enum" => [5, 10],
+              "required" => true,
+              "type" => "integer"
+            },
+            "output_resolution" => {
+              "enum" => ["720p", "1080p"],
+              "required" => true
+            },
+            "prompt" => {
+              "required" => true
+            }
+          }
+        }
+      }
+    }.freeze
+  end
+end

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

@@ -3,39 +3,49 @@
 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
 
         ENDPOINT = "/api/v1/runway/extend_video"
         RESPONSE_CLASS = Types::TaskCreateResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTaskResponse
+        MODEL = "runway"
 
         def initialize(http)
           @http = http
         end
 
-        def run(**params)
-          task = create(**params)
-          poll_until_complete { get(task.id) }
+        # 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(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
         end
 
-        def create(**params)
+        # 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(options: nil, **params)
           params = compact_params(params)
-          validate_params!(params)
-          request(:post, ENDPOINT, body: params)
+          validate_contract!(CONTRACT["extend-video"], params.merge(model: MODEL))
+          request(:post, ENDPOINT, body: params, options: options)
         end
 
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
-        end
-
-        private
-
-        def validate_params!(params)
-          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, "output_resolution is required" unless param(params, :output_resolution)
-          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
+        # Get extend-video task status by task ID.
+        #
+        # @param id [String] task ID
+        # @return [RunApi::Runway::Types::TaskResponse] current task status
+        def get(id, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
       end
     end

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

@@ -3,40 +3,51 @@
 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
 
         ENDPOINT = "/api/v1/runway/text_to_video"
         RESPONSE_CLASS = Types::TaskCreateResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTaskResponse
+        MODEL = "runway"
 
         def initialize(http)
           @http = http
         end
 
-        def run(**params)
-          task = create(**params)
-          poll_until_complete { get(task.id) }
+        # 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(options: nil, **params)
+          task = create(options: options, **params)
+          poll_until_complete { get(task.id, options: options) }
         end
 
-        def create(**params)
+        # 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(options: nil, **params)
           params = compact_params(params)
-          validate_params!(params)
-          request(:post, ENDPOINT, body: params)
+          validate_contract!(CONTRACT["text-to-video"], params.merge(model: MODEL))
+          request(:post, ENDPOINT, body: params, options: options)
         end
 
-        def get(id)
-          request(:get, "#{ENDPOINT}/#{id}")
-        end
-
-        private
-
-        def validate_params!(params)
-          raise Core::ValidationError, "prompt is required" unless param(params, :prompt)
-          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)
+        # 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, options: nil)
+          request(:get, "#{ENDPOINT}/#{id}", options: options)
         end
       end
     end

data/lib/runapi/runway/types.rb

@@ -2,19 +2,20 @@
 
 module RunApi
   module Runway
+    # Type definitions and constants for Runway Gen-4 video generation.
     module Types
-      OUTPUT_RESOLUTIONS = %w[720p 1080p].freeze
-      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 }
@@ -24,8 +25,11 @@ module RunApi
         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 }]
       end

data/lib/runapi/runway.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-runway
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - RunAPI
@@ -15,18 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
-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.
+        version: 0.3.0
+description: The Runway Ruby SDK is the language-specific package for Runway 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-runway.rb
 - lib/runapi/runway.rb
 - lib/runapi/runway/client.rb
+- lib/runapi/runway/contract_gen.rb
 - lib/runapi/runway/resources/extend_video.rb
 - lib/runapi/runway/resources/text_to_video.rb
 - lib/runapi/runway/types.rb
@@ -46,9 +47,11 @@ homepage: https://runapi.ai/models/runway
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: runway
   homepage_uri: https://runapi.ai/models/runway
   documentation_uri: https://github.com/runapi-ai/runway-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/runway-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/runway-sdk/issues
   changelog_uri: https://github.com/runapi-ai/runway-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -64,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.17
 specification_version: 4
-summary: Runway API Ruby SDK for RunAPI
+summary: Runway Ruby SDK for RunAPI
 test_files: []