kavel 0.2.0

Generate and edit images from Rust with no API key and no account, via the free tier of kavel.ai
Documentation

kavel

Generate and edit images from Rust with no API key, no account and no card.

[dependencies]
kavel = "0.1"
let img = kavel::generate(
    "matte black ceramic mug on pale oak, soft window light from the left, shallow depth of field",
    &kavel::Options { aspect_ratio: "16:9".into(), ..Default::default() },
)?;
println!("{}", img.url); // https://cdn.kavel.ai/uploads/kie/image/....webp
let img = kavel::edit(source_url, "place the mug on a white marble surface", &kavel::Options::default())?;

Or straight from a clone:

cargo run --example generate -- "an isometric coffee shop, pastel palette"
cargo run --example generate -- --edit https://example.com/portrait.jpg "give him a buzz cut"

Every other image crate wants a key from OpenAI, fal or Replicate before it runs once. This one talks to the free tier of Kavel — a client id the crate invents rather than an account you register — so cargo run works on a machine with nothing configured, including CI.

Why it is shaped this way

  • Blocking, two small dependencies. ureq and serde_json, no async runtime to pull in. Wrap it in spawn_blocking if you live inside Tokio.
  • An edit lane. edit takes a photo you already have and one sentence describing the change.
  • An error enum you can match on. Quota means wait or sign in, Rejected means reword, SignIn means the request is off the free shelf. No string parsing.
  • 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.

Limits, measured against the running service

  • The free grant is 15 credits. An image costs 5, an edit costs 15. The crate 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 Error::Quota.
  • Free output is 1K and watermarked; Image::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 has a browser lane for that.

Signing in removes the watermark and opens the full shelf: Nano Banana 2 for up to 14 reference photos, GPT Image 2 for 4K output, Qwen Image 3 when the picture has to contain correctly spelled text, and Seedream 5.0 Pro for photoreal people. Pricing 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 — the same account you use on the site — and pass it (or set KAVEL_API_KEY):

let opts = kavel::Options { api_key: Some(std::env::var("KAVEL_API_KEY")?), model: Some("gpt-image-2".into()), ..Default::default() };
let img = kavel::generate(prompt, &opts)?;

With a key every call runs on your account, exactly as it would on the site: your credits and plan, no per-IP ceiling, no watermark on a paid plan, and any image model your plan includes. Error::Auth means the key is wrong; Error::Quota 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. For edits, say what changes and the model keeps the rest; it is the same Nano Banana 2 Lite lane behind the AI hairstyle changer and the AI outfit generator. The free AI image generator runs the same engines in a browser, and the showcase has finished output.

Tests

cargo test

Offline: argument validation, client id uniqueness, the quota wall (an HTTP 200 recognised only by a field), the sign-in refusal and task id extraction.

MIT