runapi-gemini-omni 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab0124af9b8dfebb28307d7560455e2e8e7713d44ee4229df842b8a7edcc9af0
-  data.tar.gz: 4a137b6a2aa7aba8ace50db55f4eb71e78960e32e8881e5890250be48a269118
+  metadata.gz: 7befcdce5d30097c0c8ad440c86bd8cd873e14aef90f59304f60d89eed3c2a29
+  data.tar.gz: ae2353b876a73b19681e151c46310e67edf1dc2f0c04565b5a5c7b10ff3630ce
 SHA512:
-  metadata.gz: 1b165f06bdbce32a051c122726cd03c6aaa101312f8a5a96f5055a7336f0dbb91fd82c946fd4bbbf6ac40f75270d1520ad6170d9681d3ff823a72c5a05140a8f
-  data.tar.gz: c949b858a8e6a2fca6ffc6273c68f869d93bb946d37621f99390315c321227a0a27b3c4e91fb4a6e88e6fd7716977c6f35f9a0eed5abfa620239b2ed8bb0b170
+  metadata.gz: 3bc31cf371de32b41d86090294fa7feb13ca132d777fa2944ec71a13e015cafed6ef6ec1a6a0f99a8b96c0401703e63d4d38f1d1c4f4e91d0b2639a9734a940e
+  data.tar.gz: 6056184058b318efb10aaf4eacf012b571fb27d64536faa374f33e1bc182458c1e6dbd2e7cb3b0d7ef2473fc4a07fd3f655bf5d9ce259bcbb4cce672a734b3fd

data/README.md

@@ -32,6 +32,8 @@ video = client.text_to_video.run(
 )
 ```
 
+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.
+
 ## Links
 
 - Model page: https://runapi.ai/models/gemini-omni

data/lib/runapi/gemini_omni/client.rb

@@ -2,14 +2,29 @@
 
 module RunApi
   module GeminiOmni
-    class Client
-      attr_reader :create_audio, :create_character, :text_to_video
+    # Gemini Omni multimodal generation client for voice presets, character creation,
+    # and text-to-video with optional characters, audio voices, and reference media.
+    #
+    # @example
+    #   client = RunApi::GeminiOmni::Client.new(api_key: "sk-...")
+    #
+    #   audio = client.create_audio.run(audio_id: "zephyr", name: "Narrator")
+    #   video = client.text_to_video.run(
+    #     prompt: "A narrator walks through a futuristic city",
+    #     duration_seconds: 6,
+    #     audio_ids: [audio.audio.id]
+    #   )
+    #   puts video.videos.first.url
+    class Client < RunApi::Core::Client
+      # @return [Resources::CreateAudio] Registers reusable voice presets (synchronous).
+      attr_reader :create_audio
+      # @return [Resources::CreateCharacter] Builds reusable characters from reference images (synchronous).
+      attr_reader :create_character
+      # @return [Resources::TextToVideo] Generates video from prompts with optional characters and voices (async).
+      attr_reader :text_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
         @create_audio = Resources::CreateAudio.new(http)
         @create_character = Resources::CreateCharacter.new(http)
         @text_to_video = Resources::TextToVideo.new(http)

data/lib/runapi/gemini_omni/resources/create_audio.rb

@@ -3,6 +3,8 @@
 module RunApi
   module GeminiOmni
     module Resources
+      # Registers a reusable voice preset from a built-in voice identity.
+      # Synchronous -- only +run+ is available (no create/get polling).
       class CreateAudio
         include RunApi::Core::ResourceHelpers
 

data/lib/runapi/gemini_omni/resources/create_character.rb

@@ -3,6 +3,9 @@
 module RunApi
   module GeminiOmni
     module Resources
+      # Builds a reusable character from a reference image and description.
+      # Attach audio IDs to give the character a specific voice.
+      # Synchronous -- only +run+ is available (no create/get polling).
       class CreateCharacter
         include RunApi::Core::ResourceHelpers
 
@@ -10,7 +13,6 @@ module RunApi
         RESPONSE_CLASS = Types::CreateCharacterResponse
         DESCRIPTIONS_MAX_LENGTH = 20_000
         CHARACTER_NAME_MAX_LENGTH = 210
-        IMAGE_URLS_MAX = 1
 
         def initialize(http)
           @http = http
@@ -26,10 +28,8 @@ module RunApi
 
         def validate_params!(params)
           validate_required!(params, :descriptions)
-          validate_required!(params, :image_urls)
-          validate_array!(params, :image_urls)
+          validate_required!(params, :reference_image_url)
           validate_array!(params, :audio_ids) if param(params, :audio_ids)
-          validate_image_count!(params)
           validate_length!(params, :descriptions, DESCRIPTIONS_MAX_LENGTH)
           validate_length!(params, :character_name, CHARACTER_NAME_MAX_LENGTH)
         end
@@ -52,12 +52,6 @@ module RunApi
           raise Core::ValidationError, "#{key} must be an array"
         end
 
-        def validate_image_count!(params)
-          return if param(params, :image_urls).length <= IMAGE_URLS_MAX
-
-          raise Core::ValidationError, "image_urls accepts at most #{IMAGE_URLS_MAX} image"
-        end
-
         def validate_length!(params, key, max_length)
           value = param(params, key)
           return if value.nil? || value.to_s.length <= max_length

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

@@ -3,6 +3,9 @@
 module RunApi
   module GeminiOmni
     module Resources
+      # Generates video from a prompt with optional characters, audio voices,
+      # reference images, and source video clips.
+      # Async -- use +run+ for automatic polling or +create+/+get+ for manual control.
       class TextToVideo
         include RunApi::Core::ResourceHelpers
 
@@ -10,7 +13,7 @@ module RunApi
         RESPONSE_CLASS = Types::TextToVideoResponse
         COMPLETED_RESPONSE_CLASS = Types::CompletedTextToVideoResponse
         PROMPT_MAX_LENGTH = 20_000
-        IMAGE_URLS_MAX = 7
+        REFERENCE_IMAGE_URLS_MAX = 7
         AUDIO_IDS_MAX = 3
         VIDEO_LIST_MAX = 1
         CHARACTER_IDS_MAX = 3
@@ -41,12 +44,12 @@ module RunApi
 
         def validate_params!(params)
           validate_required!(params, :prompt)
-          validate_required!(params, :duration)
+          validate_required!(params, :duration_seconds)
           validate_length!(params, :prompt, PROMPT_MAX_LENGTH)
-          validate_optional!(params, :duration, Types::DURATIONS)
+          validate_optional!(params, :duration_seconds, Types::DURATIONS)
           validate_optional!(params, :aspect_ratio, Types::ASPECT_RATIOS)
-          validate_optional!(params, :resolution, Types::RESOLUTIONS)
-          validate_array!(params, :image_urls, IMAGE_URLS_MAX) if param(params, :image_urls)
+          validate_optional!(params, :output_resolution, Types::OUTPUT_RESOLUTIONS)
+          validate_array!(params, :reference_image_urls, REFERENCE_IMAGE_URLS_MAX) if param(params, :reference_image_urls)
           validate_array!(params, :audio_ids, AUDIO_IDS_MAX) if param(params, :audio_ids)
           validate_array!(params, :video_list, VIDEO_LIST_MAX) if param(params, :video_list)
           validate_array!(params, :character_ids, CHARACTER_IDS_MAX) if param(params, :character_ids)
@@ -99,12 +102,12 @@ module RunApi
         end
 
         def validate_reference_units!(params)
-          units = Array(param(params, :image_urls)).count +
+          units = Array(param(params, :reference_image_urls)).count +
             (Array(param(params, :video_list)).count * VIDEO_REFERENCE_UNITS) +
             Array(param(params, :character_ids)).count
           return if units <= REFERENCE_UNITS_MAX
 
-          raise Core::ValidationError, "image_urls + video_list*2 + character_ids must use #{REFERENCE_UNITS_MAX} reference units or fewer"
+          raise Core::ValidationError, "reference_image_urls + video_list*2 + character_ids must use #{REFERENCE_UNITS_MAX} reference units or fewer"
         end
 
         def validate_seed!(params)

data/lib/runapi/gemini_omni/types.rb

@@ -2,7 +2,9 @@
 
 module RunApi
   module GeminiOmni
+    # Type definitions and constants for the Gemini Omni API.
     module Types
+      # The 30 preset voice identities, each with distinct pitch, cadence, and personality.
       AUDIO_VOICES = %w[
         achernar achird algenib algieba alnilam aoede autonoe callirrhoe charon
         despina enceladus erinome fenrir gacrux iapetus kore laomedeia leda orus
@@ -10,42 +12,59 @@ module RunApi
         vindemiatrix zephyr zubenelgenubi
       ].freeze
 
+      # A created voice preset with its server-assigned ID.
       class Audio < RunApi::Core::BaseModel
         required :id, String
         optional :name, String
       end
 
+      # Result of a synchronous create-audio call.
       class CreateAudioResponse < RunApi::Core::BaseModel
         required :id, String
         optional :audio, -> { Audio }
         optional :error, String
       end
 
+      # URL to a generated or reference image.
+      class Image < RunApi::Core::BaseModel
+        optional :url, String
+      end
+
+      # A created character with its ID, name, and reference images.
       class Character < RunApi::Core::BaseModel
         required :id, String
         optional :name, String
-        optional :image_url, String
+        optional :images, [-> { Image }]
       end
 
+      # Result of a synchronous create-character call.
       class CreateCharacterResponse < RunApi::Core::BaseModel
         required :id, String
         optional :character, -> { Character }
         optional :error, String
       end
 
-      DURATIONS = %w[4 6 8 10].freeze
+      # Allowed video durations in seconds. Longer durations consume more credits.
+      DURATIONS = [4, 6, 8, 10].freeze
+      # Output aspect ratios: landscape (16:9) or portrait (9:16).
       ASPECT_RATIOS = %w[16:9 9:16].freeze
-      RESOLUTIONS = %w[720p 1080p 4k].freeze
+      # Output resolutions -- higher values produce sharper video at higher cost.
+      OUTPUT_RESOLUTIONS = %w[720p 1080p 4k].freeze
+      # Valid seed range for reproducible generation.
       SEED_RANGE = (0..2_147_483_647)
 
+      # URL to a generated video file.
       class Video < RunApi::Core::BaseModel
         optional :url, String
       end
 
+      # Async text-to-video task result with lifecycle status and generated videos.
       class TextToVideoResponse < RunApi::Core::TaskResponse
         optional :videos, [-> { Video }]
       end
 
+      # Narrowed response returned by +run+ once polling confirms completion.
+      # Videos are guaranteed present.
       class CompletedTextToVideoResponse < TextToVideoResponse
         required :videos, [-> { Video }]
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-gemini-omni
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -15,14 +15,14 @@ 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
+        version: 0.2.6
 description: The gemini omni api Ruby SDK is the language-specific package for Gemini
   Omni on RunAPI. Use this package for voice resources, character resources, and multimodal
   video workflows that need JSON request bodies, task status lookup, and consistent