Images

Generate an image from a prompt, or edit one or more reference images. Both endpoints take a JSON body, share the same authentication, rate-limit and quota pipeline as every other service, and return the images base64-encoded.

Method & path	Does	Billing
`POST /api/v1/images/generations`	Text → image	per image returned, `image-generation` price
`POST /api/v1/images/edits`	Reference image(s) + prompt → image	per image returned, `image-edit` price

Request

Only the fields below are read; anything else in the body is ignored.

Field	Notes
`prompt`	Required. Up to 4,000 characters.
`model`	A `company/model` slug from the platform's image models, e.g. `openai/gpt-image-2`. Omit it to use the platform default. A model that isn't offered is refused, and the error lists the ones that are.
`n`	How many images, `1`–`4`. Default `1`.
`quality`	`low`, `medium` or `high`. Defaults to `low` — see quality below.
`size`, `resolution`, `aspect_ratio`	Output dimensions, e.g. `"size": "1024x1024"` or `"aspect_ratio": "16:9"`. Which ones a model honours varies by model.
`output_format`, `output_compression`, `background`, `seed`	Optional output controls, passed to the model when it supports them.
`image` or `images`	Edits only, required. One reference (`image`) or several (`images`), each an `https://` URL or a `data:image/…` data URL. The platform sets how many references one edit may carry (never more than 8); an edit over that limit is refused, and the error states the limit.

The body must be JSON — a multipart upload is refused with 400 bad_request. To send a local file, encode it as a data URL; large images are better passed as an https:// URL (a single data URL is capped at roughly 15 MB of image).

Response

{
  "created": 1761100000,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "media_type": "image/png" }
  ]
}

One entry per image returned. media_type tells you how to decode or serve b64_json; read it defensively, as it is included whenever it is known.

Quality

quality defaults to low when you leave it out. The platform also has a maximum quality: a request above it is lowered to the maximum, not refused — ask for high and you may receive medium or low. Nothing in the response changes shape when that happens.

Billing

You pay per image returned: "n": 3 that yields three images bills three units. A request that fails bills nothing.

Generate (text → image)

curl https://khabot.com/api/v1/images/generations \
  -H "Authorization: Bearer kb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a navy origami fox on white","size":"1024x1024","quality":"low"}'

Edit (image → image)

# a reference by URL
curl https://khabot.com/api/v1/images/edits \
  -H "Authorization: Bearer kb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"make the background transparent","image":"https://example.com/source.png"}'

# a local file, as a data URL — written to a file first, because a base64 image
# is usually too long to pass as a single command-line argument
# (on macOS use: base64 -i source.png)
printf '{"prompt":"add a subtle drop shadow","image":"data:image/png;base64,%s"}' \
  "$(base64 -w0 source.png)" > body.json
curl https://khabot.com/api/v1/images/edits \
  -H "Authorization: Bearer kb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Errors

HTTP	code	When
400	`bad_request`	The body is not JSON (including a multipart upload), `prompt` is missing, `model` is not a `company/model` slug or not one the platform offers, `n` is out of range, an edit has no valid reference or more references than the platform allows — or the model rejected the parameters. The `message` says which, and lists the available models or the reference limit when those are the cause. Not billed.
503	`upstream_unavailable`	The image service could not produce an image. Not billed; safe to retry.
503	`service_not_configured`	The image service is not switched on. Not billed.

Plan, quota and rate-limit walls are the same as every other service — see Errors.