freeimagetovideo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c87a66298c7dbe96206cb7407322cb19c9ded78aa11092095fa650a98417779
+  data.tar.gz: cbbb8bfe7f7f011eb003d9fd1685c70c7fe8a80faf362164bb64cbe4f2e5c3f3
+SHA512:
+  metadata.gz: 7a56d066febdd9dcc675bbd3a115261ea3715d8bc18986a1c87b8a0aa499747eefc7f40f29beb5ede3c0fef21a7bdc0383157df7a6a7c18692a2154b7496c716
+  data.tar.gz: 6edff9ce9055fd918135668fbeb32ed309d155f498ccc82060c34688aac259fe7ab8a0313b624034beeba62800b95865f66c8f26ddb11aca859eea875d00d502

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Free Image to Video (https://freeimagetovideo.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,67 @@
+# Free Image to Video: Ruby SDK
+
+Free image to video AI with no daily cap: start with no sign-up, keep going on a free account. Every video comes with sound and no watermark. This is the official Ruby SDK for [Free Image to Video](https://freeimagetovideo.ai/?utm_source=rubygems&utm_medium=package): turn a prompt or a photo into a video clip from your Ruby code.
+
+```ruby
+require "freeimagetovideo"
+
+clip  = FreeImageToVideo.generate_video("a paper lantern drifting over a night river")
+moved = FreeImageToVideo.generate_video("the camera slowly orbits the statue",
+                                        image_url: "https://example.com/statue.jpg",
+                                        duration: 6, aspect_ratio: "9:16")
+```
+
+Each call submits the run, waits for it and returns the URL of the finished clip. With `image_url` it is [image to video AI with sound](https://freeimagetovideo.ai/video/image-to-video-ai-with-sound): your photo is the first frame. Without it, it is [free text to video AI](https://freeimagetovideo.ai/video/free-text-to-video-ai) from the prompt alone.
+
+## Install
+
+```bash
+gem install freeimagetovideo
+```
+
+Standard library only (`net/http`, `json`).
+
+## API key and plans
+
+Create a key at [freeimagetovideo.ai/settings/apikeys](https://freeimagetovideo.ai/settings/apikeys), then export it:
+
+```bash
+export FREEIMAGETOVIDEO_API_KEY=sk-...
+```
+
+API runs need a paid plan: each run draws on the plan's full-speed allowance, then waits in the relaxed queue. See [pricing](https://freeimagetovideo.ai/pricing). To make clips without a key, use the generator on [freeimagetovideo.ai](https://freeimagetovideo.ai/?utm_source=rubygems&utm_medium=package): start with no sign-up, keep going on a free account.
+
+## Options
+
+| option | values |
+|---|---|
+| `duration` | 4, 5, 6, 8, 10, 15 (seconds) |
+| `resolution` | `480p` (default), `768p` |
+| `aspect_ratio` | `16:9` (default), `9:16`, `1:1` |
+
+Model: MiniMax H3 (`minimax-h3`). Every clip comes with sound.
+
+## Lower level
+
+```ruby
+client = FreeImageToVideo::Client.new          # reads FREEIMAGETOVIDEO_API_KEY
+id   = client.submit("a koi pond in the rain")
+run  = client.status(id)   # run["status"]: pending | processing | success | failed | canceled
+url  = client.wait(id)     # polls every 10 s, gives up after 30 minutes
+left = client.credits      # credits left on the account
+```
+
+## Errors worth catching
+
+All inherit from `FreeImageToVideo::Error`:
+
+- `AuthError`: no key, or the key is wrong or deleted
+- `QuotaError`: not enough credits for this run
+- `PlanError`: API runs need a paid plan
+- `BusyError`: too many runs generating at once
+- `RejectedError`: the content filter refused the prompt, or a cooldown is active
+- `GenerationError`: the run failed or was canceled; `#error_message` says why
+- `TimeoutError`: still generating at the deadline; check the run later with `status`
+- `APIError`: any other failed request
+
+MIT licensed.

data/lib/freeimagetovideo/version.rb

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

data/lib/freeimagetovideo.rb

@@ -0,0 +1,209 @@
+# Official Ruby SDK for Free Image to Video (https://freeimagetovideo.ai).
+# Free image to video AI with no daily cap: start with no sign-up, keep going on
+# a free account. Every video comes with sound and no watermark.
+#
+#   require "freeimagetovideo"
+#   clip  = FreeImageToVideo.generate_video("a paper lantern drifting over a night river")
+#   moved = FreeImageToVideo.generate_video("the camera slowly orbits the statue",
+#                                           image_url: "https://example.com/statue.jpg")
+#
+# Set FREEIMAGETOVIDEO_API_KEY (create a key at https://freeimagetovideo.ai/settings/apikeys).
+require "json"
+require "net/http"
+require "uri"
+require_relative "freeimagetovideo/version"
+
+module FreeImageToVideo
+  BASE_URL = "https://freeimagetovideo.ai".freeze
+  KEYS_URL = "https://freeimagetovideo.ai/settings/apikeys".freeze
+  DEFAULT_MODEL = "minimax-h3".freeze
+  MODELS = ["minimax-h3"].freeze
+
+  # Base of every error this gem raises.
+  class Error < StandardError
+    attr_reader :status, :code, :reason, :task_id, :error_message, :failure_kind
+    def initialize(msg = nil, status: nil, code: nil, reason: nil, task_id: nil, error_message: nil, failure_kind: nil)
+      super(msg)
+      @status = status
+      @code = code
+      @reason = reason
+      @task_id = task_id
+      @error_message = error_message
+      @failure_kind = failure_kind
+    end
+  end
+  # No API key, or the key is invalid or deleted.
+  class AuthError < Error; end
+  # Not enough credits for this run.
+  class QuotaError < Error; end
+  # API runs need a paid plan.
+  class PlanError < Error; end
+  # Too many runs generating at once on this account.
+  class BusyError < Error; end
+  # The content filter refused the prompt, or a cooldown is active.
+  class RejectedError < Error; end
+  # The run ended as failed or canceled; #error_message says why.
+  class GenerationError < Error; end
+  # Still generating when the deadline passed; check the run later.
+  class TimeoutError < Error; end
+  # Any other failed request.
+  class APIError < Error; end
+
+  # Map an HTTP status and envelope to the error that says what to do next.
+  def self.classify(status, env)
+    env = {} unless env.is_a?(Hash)
+    msg = env["message"].to_s
+    msg = "request failed (HTTP #{status})" if msg.empty?
+    code = env["code"].is_a?(Integer) ? env["code"] : 0
+    reason = env["data"].is_a?(Hash) ? env["data"]["reason"].to_s : ""
+    klass =
+      if status == 401 then AuthError
+      elsif code == -2 || code == -3 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 APIError
+      end
+    klass.new(msg, status: status, code: code, reason: reason.empty? ? nil : reason)
+  end
+
+  # Read one answer: the envelope's data on code 0, else raise the classified error.
+  # Refusals usually arrive as HTTP 200 with a non-zero code, so the status alone is not enough.
+  def self.parse_envelope(status, raw)
+    env = {}
+    unless raw.to_s.strip.empty?
+      begin
+        env = JSON.parse(raw)
+      rescue JSON::ParserError
+        raise classify(401, {}) if status == 401
+        raise APIError.new("freeimagetovideo.ai returned a non-JSON response (HTTP #{status})", status: status)
+      end
+    end
+    return env["data"] if status < 400 && env.is_a?(Hash) && env["code"] == 0
+
+    raise classify(status, env)
+  end
+
+  # Request body for POST /api/ai/generate.
+  def self.body(prompt, image_url: nil, model: nil, **options)
+    opts = options.each_with_object({}) { |(k, v), o| o[k.to_s] = v }
+    opts["sound"] = true
+    scene = "text-to-video"
+    if image_url && !image_url.to_s.empty?
+      opts["image_input"] = [image_url.to_s]
+      scene = "image-to-video"
+    end
+    { "provider" => "auto", "mediaType" => "video", "model" => (model || DEFAULT_MODEL).to_s,
+      "scene" => scene, "prompt" => prompt, "options" => opts }
+  end
+
+  # A client bound to one API key. transport: is a callable (url, body_hash_or_nil, key) -> [status, raw_body], 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["FREEIMAGETOVIDEO_API_KEY"]).to_s.strip
+      base = (base_url || ENV["FREEIMAGETOVIDEO_BASE_URL"]).to_s.strip
+      @base = (base.empty? ? BASE_URL : base).chomp("/")
+      @poll_every = poll_every
+      @timeout = timeout
+      @transport = transport || method(:http)
+    end
+
+    # Start a run and return its task id without waiting.
+    # Options: duration (4/5/6/8/10/15), resolution ("480p"/"768p"), aspect_ratio ("16:9"/"9:16"/"1:1").
+    def submit(prompt, image_url: nil, model: nil, **options)
+      raise APIError, "prompt is required" if prompt.to_s.strip.empty?
+
+      data = post("/api/ai/generate", FreeImageToVideo.body(prompt, image_url: image_url, model: model, **options))
+      id = data.is_a?(Hash) ? data["id"] : nil
+      raise APIError, "freeimagetovideo.ai accepted the run but returned no id" if id.nil? || id.to_s.empty?
+
+      id.to_s
+    end
+
+    # Look up a run: {"id", "status" (pending|processing|success|failed|canceled), "videos", "errorMessage", "failureKind", "queued", "queueEta"}.
+    def status(task_id)
+      data = post("/api/ai/query", { "taskId" => task_id })
+      raise APIError, "unexpected status answer" unless data.is_a?(Hash)
+
+      data
+    end
+
+    # Credits left on the account.
+    def credits
+      data = post("/api/user/get-user-credits", nil)
+      data.is_a?(Hash) ? data["remainingCredits"].to_i : 0
+    end
+
+    # Submit, wait, and return the URL of the finished clip.
+    def generate_video(prompt, image_url: nil, model: nil, **options)
+      wait(submit(prompt, image_url: image_url, model: model, **options))
+    end
+
+    # Poll a submitted run until it finishes and return its video URL.
+    def wait(task_id)
+      deadline = Time.now + @timeout
+      loop do
+        t = status(task_id)
+        case t["status"]
+        when "success"
+          videos = Array(t["videos"])
+          raise GenerationError.new("freeimagetovideo: run #{task_id}: finished with no video", task_id: task_id, error_message: "finished with no video") if videos.empty?
+
+          return videos[0]
+        when "failed", "canceled"
+          em = t["errorMessage"].to_s
+          raise GenerationError.new("freeimagetovideo: generation failed: run #{task_id}: #{em.empty? ? t['status'] : em}",
+                                    task_id: task_id, error_message: em, failure_kind: t["failureKind"])
+        end
+        raise TimeoutError.new("freeimagetovideo: still generating; check run #{task_id} later", task_id: task_id) if Time.now + @poll_every > deadline
+
+        sleep @poll_every
+      end
+    end
+
+    private
+
+    def post(path, payload)
+      raise AuthError, "set FREEIMAGETOVIDEO_API_KEY (create a key at #{KEYS_URL})" if @key.empty?
+
+      status, raw = @transport.call("#{@base}#{path}", payload, @key)
+      FreeImageToVideo.parse_envelope(status, raw)
+    end
+
+    def http(url, payload, key)
+      uri = URI(url)
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{key}"
+      req["User-Agent"] = "fitv-ruby/#{VERSION}"
+      req.body = JSON.generate(payload) unless payload.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 APIError, "could not reach freeimagetovideo.ai: #{e.message}"
+    end
+  end
+
+  # Generate one clip with sound and return its URL.
+  def self.generate_video(prompt, image_url: nil, api_key: nil, **options)
+    Client.new(api_key).generate_video(prompt, image_url: image_url, **options)
+  end
+
+  # Start a run and return its task id.
+  def self.submit(prompt, image_url: nil, api_key: nil, **options)
+    Client.new(api_key).submit(prompt, 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,57 @@
+--- !ruby/object:Gem::Specification
+name: freeimagetovideo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Free Image to Video
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-10 00:00:00.000000000 Z
+dependencies: []
+description: 'Free image to video AI with no daily cap: start with no sign-up, keep
+  going on a free account. Every video comes with sound and no watermark. This is
+  the official Ruby SDK for Free Image to Video: turn a prompt or a photo into a video
+  clip with sound from Ruby, standard library only.'
+email:
+- support@freeimagetovideo.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/freeimagetovideo.rb
+- lib/freeimagetovideo/version.rb
+homepage: https://freeimagetovideo.ai/?utm_source=rubygems&utm_medium=package
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://freeimagetovideo.ai/?utm_source=rubygems&utm_medium=package
+  source_code_uri: https://github.com/hanshs474/fitv-rb
+  documentation_uri: https://freeimagetovideo.ai/video/image-to-video-ai-with-sound
+  bug_tracker_uri: https://github.com/hanshs474/fitv-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: 'Free image to video AI with no daily cap: start with no sign-up, keep going
+  on a free account. Every video comes with sound and no watermark. This is the official
+  Ruby SDK for Free Image to Video.'
+test_files: []