kavel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 679fb519c2cc395d4219b8e350479387aed76177523c661eb6f9a4b37c8bc5dd
-  data.tar.gz: 4b77c92e7c6e7cc66ffa0432cec5a71b7a9cc1e22c416e04328031bb8cfa1284
+  metadata.gz: 3414ddd1c59fa21b575190d22e60c64d4c5e2ef6c8a2c843b55b3d15a3b29a24
+  data.tar.gz: bfbd5468f1109256684a3bd7580abe178cfd7bbb8a1cd07556a7a59043cd2251
 SHA512:
-  metadata.gz: f112956669e912aa67ce9a0ddd20be03e042f2f82e9330f0dba678c8d7c956600eb7f2239b583ba7fa4e297937d2276c56f3f1135d48cb3a6be704a00fddef4d
-  data.tar.gz: 599a92a96c155b8bbcd976b76d05e23ceee3b33c0ed99db13d57bd30529302d0350f3fa6d3bb64061e1cea8495f5abed0981d6be8e53fe794064e6d9f78ef74b
+  metadata.gz: 2432f1bddc83e6102612deee1ecbcfff03546827145490977b3bddf126aab46878333525b455f5b659adbe3040f4e58e64e45a864eb81f8f48287dbaa251deab
+  data.tar.gz: 283153dc729a97e5e13a0440bd6ebd3bde8360cf82266c96558a93c12b2a840fd29a4e507aa0576fc8c244bceea8d9d986ec863b47a0edf258941080601dcb42

data/README.md

@@ -55,6 +55,20 @@ 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.
 
+## Past the free tier: an API key
+
+When the free allowance runs out, the error tells you where to go next. Create a key at
+[kavel.ai/settings/apikeys](https://www.kavel.ai/settings/apikeys?utm_source=rubygems&utm_medium=package) — the same account
+you use on the site — and pass it (or set `KAVEL_API_KEY`):
+
+```ruby
+img = Kavel.generate(prompt, api_key: ENV["KAVEL_API_KEY"], model: "gpt-image-2")
+```
+
+With a key every call runs on your account, exactly as it would on the site: your
+[credits and plan](https://www.kavel.ai/pricing?utm_source=rubygems&utm_medium=package), no per-IP ceiling, no watermark on a
+paid plan, and any image model your plan includes. `Kavel::AuthError` means the key is wrong; `Kavel::QuotaError` with a key means the account is out of credits.
+
 ## Prompts that work
 
 Name the light, the material and the composition — that moves the result more than adjectives do.

data/lib/kavel/version.rb

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

data/lib/kavel.rb

@@ -31,17 +31,23 @@ module Kavel
   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).
+  # The request needs a signed-in account, or a plan that includes this model.
   class SignInError < Error; end
+  # The API key is invalid or has been deleted.
+  class AuthError < 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.
+    #
+    # Pass +api_key:+ (a key from https://www.kavel.ai/settings/apikeys, or set
+    # KAVEL_API_KEY) to run on your account: your credits, your plan's models and
+    # no watermark on a paid plan. +model:+ is honoured only with a key.
     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",
+      run({ provider: "kie", mediaType: "image", model: pick_model(opts, MODEL_GENERATE), scene: "text-to-image",
             prompt: prompt, options: { aspect_ratio: aspect_ratio } }, **opts)
     end
 
@@ -50,7 +56,7 @@ module Kavel
       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",
+      run({ provider: "kie", mediaType: "image", model: pick_model(opts, MODEL_EDIT), scene: "image-to-image",
             prompt: instruction, options: { image_input: [source_url] } }, **opts)
     end
 
@@ -64,16 +70,19 @@ module Kavel
     def parse_submit(env)
       if env["code"] != 0
         msg = env["message"].to_s
-        raise SignInError, msg if msg.downcase.include?("sign in")
+        low = msg.downcase
+        raise AuthError, msg if low.include?("invalid api key")
+        raise QuotaError, msg if low.include?("insufficient credits")
+        raise SignInError, msg if low.include?("sign in") || low.include?("subscription")
 
         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 QuotaError, "this machine has used its #{IP_DAILY_CEILING} free credits for today — pass api_key: from #{BASE_URL}/settings/apikeys to keep going" if data["reason"] == "anon_ip_daily"
         raise SignInError, "video" if data["reason"] == "anon_unmetered_video"
 
-        raise QuotaError, "free allowance spent"
+        raise QuotaError, "free allowance spent — pass api_key: from #{BASE_URL}/settings/apikeys to keep going"
       end
       id = data["id"].to_s
       raise Error, "the service returned no task id" if id.empty?
@@ -83,19 +92,30 @@ module Kavel
 
     private
 
-    def run(payload, base_url: BASE_URL, poll_every: 5, timeout: 360, transport: nil)
+    def pick_model(opts, free)
+      key = opts[:api_key] || ENV["KAVEL_API_KEY"]
+      key && !key.empty? && opts[:model] ? opts[:model] : free
+    end
+
+    def run(payload, base_url: BASE_URL, poll_every: 5, timeout: 360, transport: nil, api_key: nil, model: 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"
+      key = api_key || ENV["KAVEL_API_KEY"]
+      key = nil if key && key.empty?
+      # With a key the account is the identity; without one, a fresh anonymous id.
+      headers = key ? { "authorization" => "Bearer #{key}" } : { "x-anon-id" => anon_id }
+      task = parse_submit(http.call(:post, "#{base_url}/api/ai/generate", payload, headers))
+
+      # Queued runs only reach the model on the poll that crosses the end of the
+      # wait, so polling is what starts the work.
       while Time.now < deadline
         sleep poll_every
         begin
-          env = http.call(:get, query, nil, id)
+          env = if key
+                  http.call(:post, "#{base_url}/api/ai/query", { taskId: task }, headers)
+                else
+                  http.call(:get, "#{base_url}/api/ai/anon-query?taskId=#{URI.encode_www_form_component(task)}&provider=kie&mediaType=image", nil, headers)
+                end
         rescue StandardError => e
           raise if e.is_a?(Error)
 
@@ -104,6 +124,9 @@ module Kavel
         next unless env["code"] == 0
 
         data = env["data"] || {}
+        clean = data["cleanImages"] || []
+        return Image.new(clean[0], false) unless clean.empty?
+
         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"])
@@ -111,10 +134,10 @@ module Kavel
       raise TimeoutError, "deadline passed"
     end
 
-    def request(verb, url, body, anon_id)
+    def request(verb, url, body, headers)
       uri = URI(url)
       req = verb == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
-      req["x-anon-id"] = anon_id
+      headers.each { |k, v| req[k] = v }
       req["user-agent"] = "kavel-rb/#{VERSION}"
       if body
         req["content-type"] = "application/json"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kavel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kavel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-09-14 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.'