movoa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c27764ce172e504594e4d5e73fb1033b33dbfb71252e6b038f8acae9c9b3499
+  data.tar.gz: 3d5c574ac6b5fa38dff69f697d0026ff3c0c33db750875e186f909dacd589666
+SHA512:
+  metadata.gz: 313b2434777fc2d16993748c8fdf8cae73a963a41d88dd3f819106eb15a61b2e1ffffe11f76d26d641615f2372be38ce4070994bedf09466fb04061c1e35af85
+  data.tar.gz: 87021147981dd72efee7bb9dd4f328284812eb6a6e6872514a693bb0c5ffab3c2f10d7ad17eccb9dfc235edc2fc544cb1b70178adf69c763d7c6eed1bbbb3faa

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Movoa (https://movoa.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# movoa
+
+Unlimited AI video generator with sound: on paid plans the tenth take of a shot costs what the first did, and your first clip is free to make right now. This is the official Ruby SDK for [Movoa](https://movoa.ai/?utm_source=rubygems&utm_medium=package): one API key turns a prompt into [text to video](https://movoa.ai/video/text-to-video), or a still into [photo to video](https://movoa.ai/video/photo-to-video), and every clip comes back as [AI video with audio](https://movoa.ai/video/ai-video-with-audio).
+
+```ruby
+require "movoa"
+
+clip = Movoa.generate_video("a paper lantern drifting over a night river, slow dolly")
+puts clip # URL of the finished MP4, sound included
+```
+
+`generate_video` submits the run, waits for it and returns the URL of the finished file.
+
+## Install
+
+```bash
+gem install movoa
+```
+
+Standard library only (`net/http`, `json`), Ruby 2.6+.
+
+## API key
+
+Sign in on [movoa.ai](https://movoa.ai/?utm_source=rubygems&utm_medium=package), create a key at [movoa.ai/settings/apikeys](https://movoa.ai/settings/apikeys), then pass it as `api_key:` or export it:
+
+```bash
+export MOVOA_API_KEY=sk-...
+```
+
+Runs cost credits on your Movoa account, at the prices on [movoa.ai/pricing](https://movoa.ai/pricing).
+
+```ruby
+Movoa.credits # remaining credits on the account
+```
+
+## Text to video and photo to video
+
+```ruby
+# text to video, vertical, 10 seconds
+Movoa.generate_video("a fox trotting through fresh snow at dawn", duration: 10, aspect_ratio: "9:16")
+
+# photo to video: the photo becomes the first frame
+Movoa.generate_video("the camera slowly orbits the statue", image_url: "https://example.com/statue.jpg")
+
+# another model
+Movoa.generate_video("a street drummer in the rain", model: "seedance-2-5", resolution: "720p")
+```
+
+| model | options |
+|---|---|
+| `minimax-h3` (default) | `duration` 4 / 5 / 6 / 8 / 10 / 15 · `resolution` 480p / 768p · `aspect_ratio` 16:9 / 9:16 / 1:1 |
+| `veo-3-1-fast` | `duration` 8 · `resolution` 720p · `aspect_ratio` 16:9 / 9:16 (photo to video: 16:9) |
+| `seedance-2-5` | `duration` 5 / 10 / 15 / 20 / 25 / 30 · `resolution` 480p / 720p · `aspect_ratio` 16:9 / 9:16 / 1:1 |
+| `seedance-2`, `seedance-2-fast`, `seedance-2-mini` | `duration` 4 / 6 / 8 / 10 · `resolution` 480p / 720p · `aspect_ratio` |
+
+Any other keyword argument is sent in `options` as it is. Every run asks for sound. On the site: [Seedance 2.5](https://movoa.ai/video/seedance-2-5) and [Veo 3](https://movoa.ai/video/google-veo-3).
+
+## Submit now, collect later
+
+```ruby
+c = Movoa::Client.new                  # reads MOVOA_API_KEY
+id = c.submit("a lighthouse in a storm", duration: 6)
+c.status(id)["status"]                 # pending | processing | success | failed | canceled
+url = c.wait(id)                       # polls every 10 seconds, 30 minutes by default
+```
+
+While a run waits in line, `status` returns `"queued" => true` and `"queueEta"` in seconds.
+
+## Errors worth rescuing
+
+All inherit from `Movoa::Error`:
+
+- `Movoa::AuthError`: no key, or the key is wrong or deleted; create one at [movoa.ai/settings/apikeys](https://movoa.ai/settings/apikeys)
+- `Movoa::QuotaError`: the account does not have enough credits for this run
+- `Movoa::PlanError`: that model or quality needs a plan on the account
+- `Movoa::BusyError`: too many runs on this account are generating at once
+- `Movoa::RejectedError`: the content filter refused the prompt, or a cooldown is active; reword it
+- `Movoa::GenerationError`: the run was accepted but failed or was canceled; `#error_message` says why
+- `Movoa::TimeoutError`: the wait ran out; `#task_id` lets you check the run later
+
+Any other refusal raises `Movoa::Error` with the server's message.
+
+MIT licensed. Made by [Movoa](https://movoa.ai/?utm_source=rubygems&utm_medium=package).

data/lib/movoa/version.rb

@@ -0,0 +1,3 @@
+module Movoa
+  VERSION = "0.1.0"
+end

data/lib/movoa.rb

@@ -0,0 +1,205 @@
+# Official SDK for Movoa (https://movoa.ai), the AI video generator with sound.
+#
+#   require "movoa"
+#   clip  = Movoa.generate_video("a paper lantern drifting over a night river")
+#   moved = Movoa.generate_video("the camera slowly orbits the statue",
+#                                image_url: "https://example.com/statue.jpg")
+#
+# Set MOVOA_API_KEY (create a key at https://movoa.ai/settings/apikeys).
+# Runs cost credits on your Movoa account, at the prices on https://movoa.ai/pricing.
+require "json"
+require "net/http"
+require "uri"
+require_relative "movoa/version"
+
+module Movoa
+  BASE_URL = "https://movoa.ai".freeze
+  KEYS_URL = "https://movoa.ai/settings/apikeys".freeze
+  DEFAULT_MODEL = "minimax-h3".freeze
+  MODELS = %w[minimax-h3 veo-3-1-fast seedance-2-5 seedance-2 seedance-2-fast seedance-2-mini].freeze
+
+  # Base of every error this gem raises. #status is the HTTP status, #code the
+  # envelope code, #reason the data.reason the service sent, if any.
+  class Error < StandardError
+    attr_reader :status, :code, :reason, :task_id
+    def initialize(msg = nil, status: nil, code: nil, reason: nil, task_id: nil)
+      super(msg)
+      @status = status
+      @code = code
+      @reason = reason
+      @task_id = task_id
+    end
+  end
+  # No API key, or the key is invalid or deleted.
+  class AuthError < Error; end
+  # The account does not have enough credits for this run.
+  class QuotaError < Error; end
+  # The model or quality needs a plan, or the account has never bought credits.
+  class PlanError < Error; end
+  # Too many runs on this account are generating at once.
+  class BusyError < Error; end
+  # The content filter refused the prompt (code -2) or a cooldown is active (code -3); reword it.
+  class RejectedError < Error; end
+  # The run was accepted but ended as failed or canceled. #error_message says why.
+  class GenerationError < Error
+    attr_reader :error_message, :failure_kind
+    def initialize(msg, task_id:, error_message: nil, failure_kind: nil)
+      super(msg, task_id: task_id)
+      @error_message = error_message
+      @failure_kind = failure_kind
+    end
+  end
+  # The wait ran out; the run may still finish. #task_id lets you check it later.
+  class TimeoutError < Error; end
+
+  # Map a refusal to the error that says what to do next. movoa.ai answers
+  # almost every refusal as HTTP 200 with a non-zero code and a data.reason.
+  def self.classify(status, body)
+    body = {} unless body.is_a?(Hash)
+    msg = body["message"].to_s
+    msg = "request failed (HTTP #{status})" if msg.empty?
+    code = body["code"].is_a?(Integer) ? body["code"] : nil
+    reason = body["data"].is_a?(Hash) && body["data"]["reason"].is_a?(String) ? body["data"]["reason"] : nil
+    klass =
+      if status == 401 then AuthError
+      elsif [-2, -3].include?(code) then RejectedError
+      elsif reason == "insufficient_credits" then QuotaError
+      elsif reason == "plan_required" then PlanError
+      elsif reason == "concurrency" then BusyError
+      elsif msg.downcase.include?("no auth") then AuthError
+      else Error
+      end
+    msg = "#{msg} (create a key at #{KEYS_URL})" if klass == AuthError && !msg.include?(KEYS_URL)
+    klass.new(msg, status: status, code: code, reason: reason)
+  end
+
+  # A client bound to one API key. transport: is a callable (url, body, key) -> [status, raw_body_string], for tests.
+  class Client
+    attr_accessor :poll_every, :timeout
+
+    def initialize(api_key = nil, base_url: nil, poll_every: 10, timeout: 1800, transport: nil)
+      @key = (api_key || ENV["MOVOA_API_KEY"]).to_s.strip
+      base = base_url || ENV["MOVOA_BASE_URL"]
+      @base = (base.nil? || base.strip.empty? ? BASE_URL : base.strip).chomp("/")
+      @poll_every = poll_every
+      @timeout = timeout
+      @transport = transport || method(:http)
+    end
+
+    # Start a run and return its task id without waiting. image_url: makes it photo to video.
+    # Other keyword arguments go into "options" as they are (duration:, resolution:, aspect_ratio:).
+    def submit(prompt, model: DEFAULT_MODEL, image_url: nil, **options)
+      raise ArgumentError, "prompt is required" if prompt.to_s.strip.empty?
+
+      opts = { "sound" => true }
+      options.each { |k, v| opts[k.to_s] = v unless v.nil? }
+      opts["image_input"] = [image_url] if image_url
+      body = {
+        # The server routes by model; this only has to be non-empty.
+        "provider" => "auto",
+        "mediaType" => "video",
+        "model" => model,
+        "scene" => image_url ? "image-to-video" : "text-to-video",
+        "prompt" => prompt,
+        "options" => opts
+      }
+      data = call("/api/ai/generate", body)["data"]
+      id = data.is_a?(Hash) ? data["id"] : nil
+      raise Error, "movoa.ai accepted the run but returned no id" if id.nil? || id.to_s.empty?
+
+      id.to_s
+    end
+
+    # Look up a run; returns the API's data hash ("id", "status", "videos", "errorMessage", "queued", "queueEta", ...).
+    def status(task_id)
+      data = call("/api/ai/query", { "taskId" => task_id })["data"]
+      data.is_a?(Hash) ? data : {}
+    end
+
+    # Credits left on the account.
+    def credits
+      data = call("/api/user/get-user-credits", nil)["data"]
+      data.is_a?(Hash) ? data["remainingCredits"].to_i : 0
+    end
+
+    # Submit, wait, and return the URL of the finished clip.
+    def generate_video(prompt, model: DEFAULT_MODEL, image_url: nil, **options)
+      wait(submit(prompt, model: model, image_url: image_url, **options))
+    end
+
+    # Wait for a submitted run and return its video URL.
+    def wait(task_id)
+      deadline = Time.now + @timeout
+      loop do
+        d = status(task_id)
+        case d["status"]
+        when "success"
+          videos = d["videos"]
+          raise GenerationError.new("run #{task_id} finished with no video", task_id: task_id) unless videos.is_a?(Array) && !videos.empty?
+
+          return videos.first.to_s
+        when "failed", "canceled"
+          em = d["errorMessage"]
+          raise GenerationError.new("run #{task_id} #{d['status']}#{em ? ": #{em}" : ''}",
+                                    task_id: task_id, error_message: em, failure_kind: d["failureKind"])
+        end
+        if Time.now + @poll_every > deadline
+          raise TimeoutError.new("run #{task_id} is still generating; check it later with status", task_id: task_id)
+        end
+
+        sleep @poll_every
+      end
+    end
+
+    private
+
+    def call(path, body)
+      raise AuthError, "set MOVOA_API_KEY or pass api_key; create a key at #{KEYS_URL}" if @key.empty?
+
+      status, raw = @transport.call("#{@base}#{path}", body, @key)
+      parsed = begin
+        raw.to_s.strip.empty? ? {} : JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+      raise Movoa.classify(401, {}) if status == 401 && !parsed.is_a?(Hash)
+      raise Error.new("movoa.ai returned a non-JSON response (HTTP #{status})", status: status) unless parsed.is_a?(Hash)
+      return parsed if status < 400 && parsed["code"] == 0
+
+      raise Movoa.classify(status, parsed)
+    end
+
+    def http(url, body, key)
+      uri = URI(url)
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{key}"
+      req["User-Agent"] = "movoa-ruby/#{VERSION}"
+      req.body = JSON.generate(body) unless body.nil?
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 60) { |h| h.request(req) }
+      [res.code.to_i, res.body.to_s]
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+      raise Error, "could not reach movoa.ai: #{e.message}"
+    end
+  end
+
+  # Generate one clip with sound (minimax-h3 by default) and return its URL.
+  def self.generate_video(prompt, model: DEFAULT_MODEL, image_url: nil, api_key: nil, **options)
+    Client.new(api_key).generate_video(prompt, model: model, image_url: image_url, **options)
+  end
+
+  # Start a run and return its task id.
+  def self.submit(prompt, model: DEFAULT_MODEL, image_url: nil, api_key: nil, **options)
+    Client.new(api_key).submit(prompt, model: model, image_url: image_url, **options)
+  end
+
+  # Look up a run.
+  def self.status(task_id, api_key: nil)
+    Client.new(api_key).status(task_id)
+  end
+
+  # Credits left on the account.
+  def self.credits(api_key: nil)
+    Client.new(api_key).credits
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: movoa
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Movoa (https://movoa.ai)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-25 00:00:00.000000000 Z
+dependencies: []
+description: 'Unlimited AI video generator with sound: on paid plans the tenth take
+  of a shot costs what the first did, and your first clip is free to make right now.
+  A zero-dependency Ruby client for Movoa (movoa.ai): text to video and photo to video
+  with sound, on MiniMax H3, Seedance 2.5, Seedance 2.0 and Veo 3.1 Fast, with one
+  API key.'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/movoa.rb
+- lib/movoa/version.rb
+homepage: https://movoa.ai/?utm_source=rubygems&utm_medium=package
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://movoa.ai/?utm_source=rubygems&utm_medium=package
+  source_code_uri: https://github.com/hanshs474/movoa-rb
+  documentation_uri: https://movoa.ai/video/text-to-video
+  bug_tracker_uri: https://github.com/hanshs474/movoa-rb/issues
+  rubygems_mfa_required: 'false'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official SDK for Movoa (movoa.ai), the AI video generator with sound.
+test_files: []