kavel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 679fb519c2cc395d4219b8e350479387aed76177523c661eb6f9a4b37c8bc5dd
+  data.tar.gz: 4b77c92e7c6e7cc66ffa0432cec5a71b7a9cc1e22c416e04328031bb8cfa1284
+SHA512:
+  metadata.gz: f112956669e912aa67ce9a0ddd20be03e042f2f82e9330f0dba678c8d7c956600eb7f2239b583ba7fa4e297937d2276c56f3f1135d48cb3a6be704a00fddef4d
+  data.tar.gz: 599a92a96c155b8bbcd976b76d05e23ceee3b33c0ed99db13d57bd30529302d0350f3fa6d3bb64061e1cea8495f5abed0981d6be8e53fe794064e6d9f78ef74b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kavel (https://www.kavel.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,80 @@
+# kavel
+
+Generate **and edit** images from Ruby with no API key, no account and no card.
+
+```bash
+gem install kavel
+```
+
+```ruby
+require "kavel"
+
+img = Kavel.generate(
+  "matte black ceramic mug on pale oak, soft window light from the left, shallow depth of field",
+  aspect_ratio: "16:9"
+)
+img.url         # => "https://cdn.kavel.ai/uploads/kie/image/....webp"
+img.watermarked # => true on the free tier
+
+edited = Kavel.edit(img.url, "place the mug on a white marble surface")
+```
+
+Every other image gem wants a key from OpenAI, fal or Replicate before it runs once. This one talks to
+the free tier of [Kavel](https://www.kavel.ai/?utm_source=rubygems&utm_medium=package) — a client id the
+gem invents rather than an account you register — so a Rake task, a Sidekiq job or a one-off script works
+on a machine with nothing configured.
+
+## Why it is shaped this way
+
+- **Standard library only.** `net/http` and `json`; nothing to conflict with your Gemfile.
+- **An edit lane.** `Kavel.edit` takes a photo you already have and one sentence describing the change.
+- **Exceptions you can rescue by intent.** `Kavel::QuotaError` means wait or sign in,
+  `Kavel::RejectedError` means reword, `Kavel::SignInError` means the request is off the free shelf.
+- **It keeps polling through a dropped connection.** A free run waits in a queue and only reaches the
+  model at the end of it; giving up on one failed poll would throw away a job about to run. A call holds
+  its thread for a minute or more, so run it from a background job, not a request cycle.
+
+## Limits, measured against the running service
+
+- The free grant is **15 credits**. An image costs **5**, an edit costs **15**. The package mints a new
+  client id per call, so a loop is not capped at three.
+- **30 credits per IP per day** sits on top — about six images from one machine — and surfaces as
+  `Kavel::QuotaError`.
+- Free output is **1K and watermarked**; `img.watermarked` tells you instead of leaving you to guess.
+- Free runs queue **25–80 seconds** before the model is called, which is why the default deadline is
+  six minutes.
+- **Video does not run anonymously** — the cheapest clip costs more than the grant. The
+  [AI video generator](https://www.kavel.ai/video?utm_source=rubygems&utm_medium=package) has a browser
+  lane for that.
+
+Signing in removes the watermark and opens the full shelf:
+[Nano Banana 2](https://www.kavel.ai/image/nano-banana-2?utm_source=rubygems&utm_medium=package) for up to
+14 reference photos, [GPT Image 2](https://www.kavel.ai/image/gpt-image-2?utm_source=rubygems&utm_medium=package)
+for 4K output, [Qwen Image 3](https://www.kavel.ai/image/qwen-image-3?utm_source=rubygems&utm_medium=package)
+when the picture has to contain correctly spelled text, and
+[Seedream 5.0 Pro](https://www.kavel.ai/image/seedream-5-pro?utm_source=rubygems&utm_medium=package) for
+photoreal people. [Pricing](https://www.kavel.ai/pricing?utm_source=rubygems&utm_medium=package) has every tier.
+
+## Prompts that work
+
+Name the light, the material and the composition — that moves the result more than adjectives do.
+For edits, say what changes and the model keeps the rest; it is the same
+[Nano Banana 2 Lite](https://www.kavel.ai/image/nano-banana-2-lite?utm_source=rubygems&utm_medium=package)
+lane behind the [AI hairstyle changer](https://www.kavel.ai/image/ai-hairstyle-changer?utm_source=rubygems&utm_medium=package)
+and the [AI outfit generator](https://www.kavel.ai/image/ai-outfit-generator?utm_source=rubygems&utm_medium=package).
+The [free AI image generator](https://www.kavel.ai/image?utm_source=rubygems&utm_medium=package) runs the
+same engines in a browser, and the [showcase](https://www.kavel.ai/showcases?utm_source=rubygems&utm_medium=package)
+has finished output.
+
+## Tests
+
+```bash
+ruby test/test_kavel.rb
+```
+
+Offline: argument validation, client id uniqueness, the quota wall (an HTTP 200 recognised only by a
+field), the sign-in refusal, and polling through a dropped connection.
+
+More languages and recipes: [kavel.readthedocs.io](https://kavel.readthedocs.io/).
+
+MIT

data/lib/kavel/version.rb

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

data/lib/kavel.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+require_relative "kavel/version"
+
+# Generate and edit images with no API key and no account.
+#
+# Calls the free tier of https://www.kavel.ai, which meters its allowance
+# against a client id this library invents rather than an account you register.
+# Measured against the running service: 15 credits per id, 5 per image, 15 per
+# edit, 30 per IP per day. Free output is 1K and watermarked.
+module Kavel
+  BASE_URL = "https://www.kavel.ai"
+  ANON_GRANT = 15
+  COST_TEXT_TO_IMAGE = 5
+  COST_EDIT = 15
+  IP_DAILY_CEILING = 30
+  MODEL_GENERATE = "kavel-image-v1"
+  MODEL_EDIT = "nano-banana-2-lite"
+
+  # One finished picture. +url+ is a permanent CDN link; +watermarked+ says
+  # whether a mark was actually drawn.
+  Image = Struct.new(:url, :watermarked)
+
+  # Base error. Rescue the subclass that matches what you want to do next.
+  class Error < StandardError; end
+  # The free allowance is spent for this id or this machine today. Wait, or sign in.
+  class QuotaError < Error; end
+  # The content filter or model refused the prompt. Reword it.
+  class RejectedError < Error; end
+  # The request needs a signed-in account (video, or a model off the free shelf).
+  class SignInError < Error; end
+  # The deadline passed while the job was queued or running.
+  class TimeoutError < Error; end
+
+  class << self
+    # Turn a prompt into a new image. Name the light, the material and the composition.
+    def generate(prompt, aspect_ratio: "1:1", **opts)
+      raise ArgumentError, "prompt is required" if prompt.to_s.strip.empty?
+
+      run({ provider: "kie", mediaType: "image", model: MODEL_GENERATE, scene: "text-to-image",
+            prompt: prompt, options: { aspect_ratio: aspect_ratio } }, **opts)
+    end
+
+    # Rewrite an existing image. +source_url+ must be a public http(s) url.
+    def edit(source_url, instruction, **opts)
+      raise ArgumentError, "source_url must be a public http(s) url" unless source_url.to_s =~ %r{\Ahttps?://}
+      raise ArgumentError, "instruction is required" if instruction.to_s.strip.empty?
+
+      run({ provider: "kie", mediaType: "image", model: MODEL_EDIT, scene: "image-to-image",
+            prompt: instruction, options: { image_input: [source_url] } }, **opts)
+    end
+
+    # A fresh client id. A reused id walls partway through a loop.
+    def anon_id
+      "rb-#{SecureRandom.hex(8)}"
+    end
+
+    # Interpret the submit response. The quota wall answers HTTP 200 with code 0,
+    # so it can only be recognised by a field.
+    def parse_submit(env)
+      if env["code"] != 0
+        msg = env["message"].to_s
+        raise SignInError, msg if msg.downcase.include?("sign in")
+
+        raise Error, msg
+      end
+      data = env["data"] || {}
+      if data["wall"] == true
+        raise QuotaError, "this machine has used its #{IP_DAILY_CEILING} credits for today" if data["reason"] == "anon_ip_daily"
+        raise SignInError, "video" if data["reason"] == "anon_unmetered_video"
+
+        raise QuotaError, "free allowance spent"
+      end
+      id = data["id"].to_s
+      raise Error, "the service returned no task id" if id.empty?
+
+      id
+    end
+
+    private
+
+    def run(payload, base_url: BASE_URL, poll_every: 5, timeout: 360, transport: nil)
+      http = transport || method(:request)
+      deadline = Time.now + timeout
+      id = anon_id
+      task = parse_submit(http.call(:post, "#{base_url}/api/ai/generate", payload, id))
+
+      # Free runs queue 25-80s and only reach the model on the poll that crosses
+      # the end of it, so polling is what starts the work.
+      query = "#{base_url}/api/ai/anon-query?taskId=#{URI.encode_www_form_component(task)}&provider=kie&mediaType=image"
+      while Time.now < deadline
+        sleep poll_every
+        begin
+          env = http.call(:get, query, nil, id)
+        rescue StandardError => e
+          raise if e.is_a?(Error)
+
+          next # a dropped poll is not a failed generation
+        end
+        next unless env["code"] == 0
+
+        data = env["data"] || {}
+        images = data["images"] || []
+        return Image.new(images[0], (data["watermarked"] || [])[0] == true) unless images.empty?
+        raise RejectedError, "prompt refused" if %w[failed error].include?(data["status"])
+      end
+      raise TimeoutError, "deadline passed"
+    end
+
+    def request(verb, url, body, anon_id)
+      uri = URI(url)
+      req = verb == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+      req["x-anon-id"] = anon_id
+      req["user-agent"] = "kavel-rb/#{VERSION}"
+      if body
+        req["content-type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 60) { |h| h.request(req) }
+      JSON.parse(res.body)
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: kavel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kavel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-13 00:00:00.000000000 Z
+dependencies: []
+description: 'A zero-dependency client for the free tier of kavel.ai: text-to-image
+  and image editing without an API key, an account or a card.'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kavel.rb
+- lib/kavel/version.rb
+homepage: https://www.kavel.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.kavel.ai
+  source_code_uri: https://github.com/hanshs474/kavel-rb
+  documentation_uri: https://kavel.readthedocs.io/
+  bug_tracker_uri: https://github.com/hanshs474/kavel-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: Generate and edit images from Ruby with no API key and no account
+test_files: []