Metadata-Version: 2.4
Name: kavel
Version: 0.2.1
Summary: Generate and edit images from Python with no API key, or on your kavel.ai account with one
Author: Kavel
License: MIT
Project-URL: Homepage, https://www.kavel.ai/?utm_source=pypi
Project-URL: Image tools, https://www.kavel.ai/image?utm_source=pypi
Project-URL: Video tools, https://www.kavel.ai/video?utm_source=pypi
Project-URL: Source, https://github.com/hanshs474/kavel-py
Project-URL: Documentation, https://kavel.readthedocs.io/
Keywords: ai,image-generation,text-to-image,image-editing,no-api-key
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# kavel

Generate images from a prompt with **no API key and no account**.

```python
from kavel import generate

url = generate("a paper-cut layered mountain range at dusk, warm rim light")
```

That is the whole setup. No key to fetch, no config file, no dependencies —
standard library only. It calls the anonymous endpoint on
[Kavel](https://www.kavel.ai/?utm_source=pypi&utm_medium=package), an online AI image and video studio.

## Editing a photo

Pass `image_url` and the prompt describes the change rather than the picture:

```python
url = generate(
    "restyle the hair into a shoulder-length layered cut, "
    "keep the same face, skin and lighting",
    image_url="https://example.com/portrait.jpg",
)
```

Naming what must stay is what holds the likeness. Prompts that only name the
edit tend to drift the whole face.

## What the free tier actually covers

| | |
|---|---|
| Anonymous grant | 15 credits |
| Text-to-image | 5 credits — so the grant covers three |
| Photo edit (`nano-banana-2-lite`) | 15 credits — exactly one |
| Per-IP ceiling | 30 credits a day |

Anonymous output is 1K and watermarked. Signing in on
[kavel.ai](https://www.kavel.ai/?utm_source=pypi&utm_medium=package) removes the watermark and opens the
larger models.

**Video is deliberately not exposed here.** The cheapest clip is 40 credits
against a 15-credit anonymous wallet, so a signed-out call cannot succeed at
any setting. Signed-out video on the site runs on a browser-side engine
instead — see [the video tools](https://www.kavel.ai/video?utm_source=pypi&utm_medium=package).

## Errors worth catching

Each failure is its own subclass of `KavelError`, so you can branch on what to do next:

- `QuotaError` — the free allowance (or, with a key, your account's credits) is spent
- `RejectedError` — the content filter refused the prompt; rewrite it rather than retrying
- `SignInError` — the request needs an account or a plan that includes that model
- `AuthError` — the API key is wrong or deleted

## 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=pypi&utm_medium=package) — the same account
you use on the site — and pass it (or set `KAVEL_API_KEY`):

```python
url = generate(prompt, api_key=os.environ["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=pypi&utm_medium=package), no per-IP ceiling, no watermark on a
paid plan, and any image model your plan includes. `AuthError` means the key is wrong; `QuotaError` with a key means the account is out of credits.

## Prompts that work

Kavel keeps a page per edit, each preloaded with a prompt for that specific
job — [hairstyle](https://www.kavel.ai/image/ai-hairstyle-changer?utm_source=pypi&utm_medium=package),
[outfit](https://www.kavel.ai/image/ai-outfit-generator?utm_source=pypi&utm_medium=package),
and the rest under [image tools](https://www.kavel.ai/image?utm_source=pypi&utm_medium=package).

MIT licensed.
