README

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

composer require hanshs474/kavel

$kavel = new Kavel\Kavel();

$img = $kavel->generate(
    'matte black ceramic mug on pale oak, soft window light from the left, shallow depth of field',
    '16:9',
);
echo $img->url; // https://cdn.kavel.ai/uploads/kie/image/....webp

$edited = $kavel->edit($img->url, 'place the mug on a white marble surface');

Every other image package 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 package invents rather than an account you register — so it works on shared hosting, in a Laravel queue job or a WordPress cron with nothing configured.

Why it is shaped this way

No dependencies beyond ext-curl. No Guzzle version to fight with your framework over.
An edit lane. edit() takes a photo you already have and one sentence describing the change.
One exception with a kind. quota means wait or sign in, rejected means reword, sign_in 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. Because the call blocks for a minute or more, run it from a queue worker, not inside a web request.

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 a quota exception.
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 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):

$kavel = new Kavel\Kavel(apiKey: getenv('KAVEL_API_KEY'), model: 'gpt-image-2');
$img = $kavel->generate($prompt);

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. KavelException::AUTH means the key is wrong; 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

php tests/run.php

Offline, no framework: 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.

MIT

hanshs474 / kavel

Package info

Security

Statistics