kavel

# Kavel

Generate AI images from Elixir with **no API key and no account**.

```elixir
def deps do
  [{:kavel, "~> 0.1"}]
end
```

```elixir
{:ok, img} = Kavel.generate("matte black ceramic mug on pale oak, soft window light",
                            aspect_ratio: "16:9")
img.url          #=> "https://cdn.kavel.ai/uploads/kie/image/....webp"
img.watermarked  #=> true on the free tier
```

Every other image client wants a key from OpenAI, fal or Replicate before it runs once. This one
calls the anonymous tier of [Kavel](https://www.kavel.ai/?utm_source=hex&utm_medium=package),
an online AI image and video studio, with a client id it invents instead of an account you register.
It needs nothing beyond OTP's `:httpc` and `Jason`.

## Errors you can match on

```elixir
case Kavel.generate("a lighthouse at dusk, oil painting") do
  {:ok, img} -> img.url
  {:error, :quota, _} -> "free allowance spent for today"
  {:error, :rejected, _} -> "reword the prompt"
  {:error, _reason, message} -> message
end
```

Reasons: `:quota`, `:rejected`, `:sign_in`, `:auth`, `:timeout`, `:other`.

## The free tier

`Kavel.credits()` reads what a fresh client id is granted, and the call costs nothing. On 2026-10-02 the
grant was 5 credits, one generated image spent all five, and one IP got two images that day. Free
output is 1K and watermarked, and free runs queue before the model starts, so the default deadline
is six minutes.

## Editing a photo

```elixir
Kavel.edit("https://example.com/portrait.jpg",
           "shoulder-length layered haircut, keep the same face, skin and lighting",
           api_key: System.get_env("KAVEL_API_KEY"))
```

An edit costs more than the free grant, so it needs a key from
[kavel.ai/settings/apikeys](https://www.kavel.ai/settings/apikeys?utm_source=hex&utm_medium=package).
Without one it returns `{:error, :quota, _}` before anything is charged.

## License

MIT. Generated with [Kavel AI](https://www.kavel.ai/?utm_source=hex&utm_medium=package).