# Images
`POST /v1/images/generations` creates a picture from a prompt, and `POST /v1/images/edits` changes pictures you send.
Both accept OpenAI's image request format, so you can use the OpenAI SDKs by changing the base URL to Keln's. API keys,
rate limits and balance work the same as for chat completions.
=== "Python"
```python
import base64
from openai import OpenAI
client = OpenAI(base_url="https://api.keln.ai/v1", api_key="sk-keln-…")
result = client.images.generate(
model="google/gemini-nano-banana-2.1",
prompt="A lighthouse on a cliff at dawn, watercolor.",
)
with open("lighthouse.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
```
=== "TypeScript"
```typescript
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.keln.ai/v1", apiKey: "sk-keln-…" });
const result = await client.images.generate({
model: "google/gemini-nano-banana-2.1",
prompt: "A lighthouse on a cliff at dawn, watercolor.",
});
fs.writeFileSync("lighthouse.png", Buffer.from(result.data[0].b64_json, "base64"));
```
=== "cURL"
```bash
curl https://api.keln.ai/v1/images/generations \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-nano-banana-2.1", "prompt": "A lighthouse on a cliff at dawn, watercolor."}' \
| jq -r '.data[0].b64_json' | base64 --decode > lighthouse.png
```
The answer holds the picture as base64, with its size, its type and the usage ([Answer](#answer)). Every image model
takes the same requests. Find them in [`GET /v1/models`](models.md) as the rows whose `output_modalities` is `["image"]`,
each listing what a request may ask of it in `supported_parameters`.
## Request
Send the request to `POST /v1/images/generations` as a JSON body, as with OpenAI.
| Field | Contract |
|---|---|
| `model` | Required. An image model id from [`GET /v1/models`](models.md). Keln returns `400 wrong_endpoint` for a chat model on this endpoint, and for an image model on chat completions. |
| `prompt` | Required. What to draw, up to 32,000 characters. |
| `size` | `auto` or left out: the model's default size. Or one of the model's exact sizes ([Sizes](#sizes)), or one of its resolutions, such as `2K`. A size the model doesn't have returns `400 param_not_supported` naming the sizes it has: Keln never draws a near size instead. |
| `aspect_ratio`, `resolution` | Optional, instead of `size`: one of the model's ratios, such as `16:9`, and one of its resolutions, such as `2K`. Beside a `size` they must agree with it. |
| `output_format` | One of the model's file types, listed in `supported_parameters`; `png` when left out. A type the model doesn't write returns `400 param_not_supported`. |
| `n` | `1` or left out. These models make one picture per request: send one request per picture. |
| `stream` | `true` answers with one `image_generation.completed` event and then `data: [DONE]`. |
| `response_format` | `b64_json` or left out. `url` returns `400 param_not_supported`: Keln keeps no copy to link to. |
| `quality`, `background`, `moderation` | `auto` or left out (`background` also takes `opaque`). These models have no such setting. |
| `input_references` | Optional. Pictures to start from, as on the edit endpoint: see [Editing](#editing). |
| `provider`, `session_id`, `trace`, `user`, `safety_identifier` | Accepted. Keln removes them before forwarding the request ([privacy](../capabilities/privacy.md)). |
`output_compression`, `style`, `seed` and `partial_images` above 0 return `400 param_not_supported`. Keln returns
`400 invalid_request` for any other field.
## Editing
`POST /v1/images/edits` takes the same fields plus the pictures to change, up to the model's limit: `input_references` in
its `supported_parameters`. Say in the prompt what to change and what to keep: Keln's image models take no mask.
=== "Python"
```python
result = client.images.edit(
model="google/gemini-nano-banana-2.1",
image=[open("room.png", "rb"), open("lamp.png", "rb")],
prompt="Put the lamp from the second picture on the desk in the first. Keep everything else as it is.",
)
```
=== "TypeScript"
```typescript
import { toFile } from "openai";
const result = await client.images.edit({
model: "google/gemini-nano-banana-2.1",
image: [await toFile(fs.createReadStream("room.png")), await toFile(fs.createReadStream("lamp.png"))],
prompt: "Put the lamp from the second picture on the desk in the first. Keep everything else as it is.",
});
```
=== "cURL"
```bash
curl https://api.keln.ai/v1/images/edits \
-H "Authorization: Bearer $KELN_API_KEY" \
-F model=google/gemini-nano-banana-2.1 \
-F "image[]=@room.png" -F "image[]=@lamp.png" \
-F "prompt=Put the lamp from the second picture on the desk in the first. Keep everything else as it is." \
| jq -r '.data[0].b64_json' | base64 --decode > room-with-lamp.png
```
The pictures can come three ways:
- **As files**, in a `multipart/form-data` request, each named `image`, or `image[]` for several. This is how the OpenAI
SDKs send them.
- **In a JSON body**, in `images`: each a base64 data URL (`data:image/png;base64,...`), a public `https://` link, or an
object with `image_url`.
- **As `input_references`**, in a JSON body on either endpoint: `[{"type": "image_url", "image_url": {"url": "..."}}]`.
PNG, JPEG, WebP, HEIC and HEIF are taken, told by each file's own bytes. A link is fetched by the model's provider, never
by Keln. Without a `size`, `aspect_ratio` or `resolution`, the model follows the
shape of your picture, and the answer's `size` says what it drew. `mask`, `markup` and `input_fidelity` return
`400 param_not_supported`, and a file id returns `400 param_not_supported`: Keln keeps no files.
## Answer
```json
{
"created": 1794290000,
"data": [{"b64_json": "iVBORw0KGgo...", "media_type": "image/png"}],
"background": "opaque",
"output_format": "png",
"size": "1024x1024",
"usage": {
"input_tokens": 15, "output_tokens": 1647, "total_tokens": 1662,
"input_tokens_details": {"text_tokens": 15, "image_tokens": 0},
"output_tokens_details": {"image_tokens": 1120, "text_tokens": 527},
"cost": 0.04286
}
}
```
`size` and `media_type` are the file's own, read from its header. The file is the model's, unchanged: any watermark or
signed Content Credentials its maker adds to mark it as AI-made pass through as they are. With `stream: true` the same fields come in one `image_generation.completed` event
(`image_edit.completed` on the edit endpoint), then `data: [DONE]`.
## Sizes
Each image model lists the sizes it draws in its `supported_parameters` in [`GET /v1/models`](models.md): `size` has every
`WIDTHxHEIGHT`, and `aspect_ratio` and `resolution` the ratios and resolutions they combine. Ask by `size`, or by
`aspect_ratio` and `resolution`. To read one model's list:
```bash
curl -s https://api.keln.ai/v1/models \
| jq '.data[] | select(.id == "google/gemini-nano-banana-2.1") | .supported_parameters'
```
## Limits
- **One picture per request.** Send `n` above 1 and Keln returns `400 param_not_supported`.
- **Pictures per edit:** up to the model's `input_references` limit, and **50 MB of pictures sent with one request**, all
together. Links don't count toward the 50 MB. Over it, Keln returns `413 request_too_large`.
- **Time.** A picture takes from about 10 seconds to half a minute, longer at higher resolutions. Keep your client's
timeout above a minute.
## Billing
Keln bills image models **per token**: your prompt and any pictures you send at the model's input price, the model's thinking
and any words it writes beside the picture at its output price, and the picture at its image price.
[`GET /v1/models`](models.md) lists the three per token in `pricing.prompt`, `pricing.completion` and
`pricing.image_output`; [Models & pricing](../models-pricing.md) shows them per million tokens.
A picture is a fixed number of image tokens for its resolution, listed on each model's page on
[keln.ai](https://keln.ai/models). Each picture you send counts as a fixed number of input tokens, shown in
`usage.input_tokens_details.image_tokens`. A model that thinks before it draws bills its thinking as output, and that
varies from request to request. The answer's `usage` says what was billed, and `usage.cost` the exact charge in USD.
Before the request is sent, Keln reserves an estimate of the cost against your balance, as it does for tokens on chat, and
then bills the tokens the model reports. A request the model's filter blocks is not billed.
## Blocked requests
The model's maker filters every request. A prompt or picture its filter refuses returns OpenAI's error for a blocked
request: `400`, with `type` `image_generation_user_error`, `code` `moderation_blocked`, and
`moderation_details.moderation_stage` saying whether the prompt (`input`) or the picture (`output`) was stopped. Change
the prompt before you send it again. The [acceptable use policy](https://keln.ai/terms) applies to every request.
## Errors
| Code | Meaning |
|---|---|
| `moderation_blocked` | The model's filter refused the prompt, a picture you sent, or the picture it drew. Not billed. |
| `param_not_supported` | A setting the model doesn't have as sent: a size it doesn't draw, `n` above 1, `url`, a mask, a file id, more pictures than it takes, or a picture type it doesn't read. The message names what the model has. |
| `request_too_large` | `413`: the pictures sent with the request are over 50 MB in all. |
| `wrong_endpoint` | A chat model on an image endpoint, or an image model on chat completions. |
| `invalid_request` | A field Keln doesn't take, or a malformed one: no `prompt`, an edit with no picture, a file that isn't an image, a data URL that isn't base64. |
| `503` | Keln couldn't serve the request just now. Retry shortly. |
Images
POST /v1/images/generations creates a picture from a prompt, and POST /v1/images/edits changes pictures you send.
Both accept OpenAI's image request format, so you can use the OpenAI SDKs by changing the base URL to Keln's. API keys,
rate limits and balance work the same as for chat completions.
importbase64fromopenaiimportOpenAIclient=OpenAI(base_url="https://api.keln.ai/v1",api_key="sk-keln-…")result=client.images.generate(model="google/gemini-nano-banana-2.1",prompt="A lighthouse on a cliff at dawn, watercolor.",)withopen("lighthouse.png","wb")asf:f.write(base64.b64decode(result.data[0].b64_json))
importfsfrom"node:fs";importOpenAIfrom"openai";constclient=newOpenAI({baseURL:"https://api.keln.ai/v1",apiKey:"sk-keln-…"});constresult=awaitclient.images.generate({model:"google/gemini-nano-banana-2.1",prompt:"A lighthouse on a cliff at dawn, watercolor.",});fs.writeFileSync("lighthouse.png",Buffer.from(result.data[0].b64_json,"base64"));
curlhttps://api.keln.ai/v1/images/generations\-H"Authorization: Bearer $KELN_API_KEY"\-H"Content-Type: application/json"\-d'{"model": "google/gemini-nano-banana-2.1", "prompt": "A lighthouse on a cliff at dawn, watercolor."}'\|jq-r'.data[0].b64_json'|base64--decode>lighthouse.png
The answer holds the picture as base64, with its size, its type and the usage (Answer). Every image model
takes the same requests. Find them in GET /v1/models as the rows whose output_modalities is ["image"],
each listing what a request may ask of it in supported_parameters.
Request
Send the request to POST /v1/images/generations as a JSON body, as with OpenAI.
Field
Contract
model
Required. An image model id from GET /v1/models. Keln returns 400 wrong_endpoint for a chat model on this endpoint, and for an image model on chat completions.
prompt
Required. What to draw, up to 32,000 characters.
size
auto or left out: the model's default size. Or one of the model's exact sizes (Sizes), or one of its resolutions, such as 2K. A size the model doesn't have returns 400 param_not_supported naming the sizes it has: Keln never draws a near size instead.
aspect_ratio, resolution
Optional, instead of size: one of the model's ratios, such as 16:9, and one of its resolutions, such as 2K. Beside a size they must agree with it.
output_format
One of the model's file types, listed in supported_parameters; png when left out. A type the model doesn't write returns 400 param_not_supported.
n
1 or left out. These models make one picture per request: send one request per picture.
stream
true answers with one image_generation.completed event and then data: [DONE].
response_format
b64_json or left out. url returns 400 param_not_supported: Keln keeps no copy to link to.
quality, background, moderation
auto or left out (background also takes opaque). These models have no such setting.
input_references
Optional. Pictures to start from, as on the edit endpoint: see Editing.
Accepted. Keln removes them before forwarding the request (privacy).
output_compression, style, seed and partial_images above 0 return 400 param_not_supported. Keln returns
400 invalid_request for any other field.
Editing
POST /v1/images/edits takes the same fields plus the pictures to change, up to the model's limit: input_references in
its supported_parameters. Say in the prompt what to change and what to keep: Keln's image models take no mask.
result=client.images.edit(model="google/gemini-nano-banana-2.1",image=[open("room.png","rb"),open("lamp.png","rb")],prompt="Put the lamp from the second picture on the desk in the first. Keep everything else as it is.",)
import{toFile}from"openai";constresult=awaitclient.images.edit({model:"google/gemini-nano-banana-2.1",image:[awaittoFile(fs.createReadStream("room.png")),awaittoFile(fs.createReadStream("lamp.png"))],prompt:"Put the lamp from the second picture on the desk in the first. Keep everything else as it is.",});
curlhttps://api.keln.ai/v1/images/edits\-H"Authorization: Bearer $KELN_API_KEY"\-Fmodel=google/gemini-nano-banana-2.1\-F"image[]=@room.png"-F"image[]=@lamp.png"\-F"prompt=Put the lamp from the second picture on the desk in the first. Keep everything else as it is."\|jq-r'.data[0].b64_json'|base64--decode>room-with-lamp.png
The pictures can come three ways:
As files, in a multipart/form-data request, each named image, or image[] for several. This is how the OpenAI
SDKs send them.
In a JSON body, in images: each a base64 data URL (data:image/png;base64,...), a public https:// link, or an
object with image_url.
As input_references, in a JSON body on either endpoint: [{"type": "image_url", "image_url": {"url": "..."}}].
PNG, JPEG, WebP, HEIC and HEIF are taken, told by each file's own bytes. A link is fetched by the model's provider, never
by Keln. Without a size, aspect_ratio or resolution, the model follows the
shape of your picture, and the answer's size says what it drew. mask, markup and input_fidelity return
400 param_not_supported, and a file id returns 400 param_not_supported: Keln keeps no files.
size and media_type are the file's own, read from its header. The file is the model's, unchanged: any watermark or
signed Content Credentials its maker adds to mark it as AI-made pass through as they are. With stream: true the same fields come in one image_generation.completed event
(image_edit.completed on the edit endpoint), then data: [DONE].
Sizes
Each image model lists the sizes it draws in its supported_parameters in GET /v1/models: size has every
WIDTHxHEIGHT, and aspect_ratio and resolution the ratios and resolutions they combine. Ask by size, or by
aspect_ratio and resolution. To read one model's list:
One picture per request. Send n above 1 and Keln returns 400 param_not_supported.
Pictures per edit: up to the model's input_references limit, and 50 MB of pictures sent with one request, all
together. Links don't count toward the 50 MB. Over it, Keln returns 413 request_too_large.
Time. A picture takes from about 10 seconds to half a minute, longer at higher resolutions. Keep your client's
timeout above a minute.
Billing
Keln bills image models per token: your prompt and any pictures you send at the model's input price, the model's thinking
and any words it writes beside the picture at its output price, and the picture at its image price.
GET /v1/models lists the three per token in pricing.prompt, pricing.completion and
pricing.image_output; Models & pricing shows them per million tokens.
A picture is a fixed number of image tokens for its resolution, listed on each model's page on
keln.ai. Each picture you send counts as a fixed number of input tokens, shown in
usage.input_tokens_details.image_tokens. A model that thinks before it draws bills its thinking as output, and that
varies from request to request. The answer's usage says what was billed, and usage.cost the exact charge in USD.
Before the request is sent, Keln reserves an estimate of the cost against your balance, as it does for tokens on chat, and
then bills the tokens the model reports. A request the model's filter blocks is not billed.
Blocked requests
The model's maker filters every request. A prompt or picture its filter refuses returns OpenAI's error for a blocked
request: 400, with typeimage_generation_user_error, codemoderation_blocked, and
moderation_details.moderation_stage saying whether the prompt (input) or the picture (output) was stopped. Change
the prompt before you send it again. The acceptable use policy applies to every request.
Errors
Code
Meaning
moderation_blocked
The model's filter refused the prompt, a picture you sent, or the picture it drew. Not billed.
param_not_supported
A setting the model doesn't have as sent: a size it doesn't draw, n above 1, url, a mask, a file id, more pictures than it takes, or a picture type it doesn't read. The message names what the model has.
request_too_large
413: the pictures sent with the request are over 50 MB in all.
wrong_endpoint
A chat model on an image endpoint, or an image model on chat completions.
invalid_request
A field Keln doesn't take, or a malformed one: no prompt, an edit with no picture, a file that isn't an image, a data URL that isn't base64.
503
Keln couldn't serve the request just now. Retry shortly.