san8888/kavel repository overview

⁠kavel — generate or edit an image from the command line, no API key

docker run --rm san8888/kavel "an isometric coffee shop, pastel palette"
# https://cdn.kavel.ai/uploads/kie/image/....webp

A 6 MB scratch image with one static binary. No key, no account, no environment variables: it talks to the free tier of Kavel⁠, an AI image and video studio, using a client id it makes up per run.

⁠Usage

# generate, with an aspect ratio
docker run --rm san8888/kavel -ratio 16:9 "matte black ceramic mug on pale oak, soft window light"

# edit an image you already have (public http(s) url)
docker run --rm san8888/kavel -edit https://example.com/portrait.jpg "give him a short textured crop, keep the face"

# use the url in a script
URL=$(docker run --rm san8888/kavel "flat illustration of a rocket, purple and orange" | tail -1)

Past the free tier, pass an API key from kavel.ai/settings/apikeys⁠ and pick any model your plan includes — calls then run on your account, with no per-IP ceiling and no watermark on a paid plan:

docker run --rm -e KAVEL_API_KEY san8888/kavel -model gpt-image-2 "a product shot of a glass perfume bottle"

Runs on linux/amd64 and linux/arm64. Handy in CI jobs, cron containers and anywhere installing a language runtime just to make one picture is overkill.

⁠Limits, measured against the running service

• Free grant 15 credits per client id; an image costs 5, an edit costs 15.
• 30 credits per IP per day — about six images from one machine. The container exits non-zero with a quota message when that is reached.
• Output is 1K and watermarked; jobs wait 25–80 s in the free queue before the model starts.
• Video is not available on the free tier.

Signing in on kavel.ai removes the watermark and opens the larger models — Nano Banana 2⁠, GPT Image 2⁠, Seedream 5.0 Pro⁠ — and the AI video generator⁠. Pricing⁠.

⁠Edits that keep the likeness

Say what changes and what stays. The edit engine, Nano Banana 2 Lite⁠, keeps what it can still see and invents what it cannot. Tuned prompts to copy from: the AI hairstyle changer⁠ and the AI outfit generator⁠.

⁠Same thing from code

Built from kavel-go⁠. SDKs for Python, Rust, TypeScript, PHP, Ruby and Dart, plus a GitHub Action: kavel.readthedocs.io⁠.

MIT