Skip to content

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.

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))
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 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). 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.
provider, session_id, trace, user, safety_identifier 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";

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 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

{
  "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: 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:

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 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 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 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.