# Images

> Generate and edit images with POST /v1/images/generations and /v1/images/edits, paid with a key or per request with x402.

Section: Developers. Web page: https://docs.katara.com/developers/images/

`POST https://api.katara.com/v1/images/generations` takes the OpenAI image generation request and returns one image. `POST https://api.katara.com/v1/images/edits` changes pictures you send. Every image request goes to Katara Cortex, whatever `model` it names, and Cortex makes the picture with one of two models:

- The main image model, which generates and edits. It is sized by tier (`1K`, `2K` or `4K`) and aspect ratio. Cortex uses it while it is available.
- A lower-cost image model, which generates only and handles posters, diagrams and text inside the picture. It makes a generation when the main model cannot, at its own lower price.

```sh
curl https://api.katara.com/v1/images/generations \
  -H "Authorization: Bearer $KATARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"katara/cortex","prompt":"A watercolor koi pond at dawn","aspect_ratio":"16:9"}'
```

With the OpenAI client, `client.images.generate(model="katara/cortex", prompt="...")` works unchanged.

## What a generation takes

| Field | |
|---|---|
| `model` | Any name. `katara/cortex` is the usual one; every name is served by Cortex. |
| `prompt` | What to draw, up to 4,000 characters. |
| `aspect_ratio` | `1:1` (the default), `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9` or `21:9`. |
| `image_size` | `1K` (the default), `2K` or `4K`. |
| `size` | `WIDTHxHEIGHT`, in place of `image_size` and `aspect_ratio`: it picks the nearest aspect ratio and the smallest tier with that many pixels. |
| `quality` | Read when the lower-cost model makes the picture: `hd` (the default, about 20 seconds) or `standard` (5 to 10 seconds). `high` and `auto` mean `hd`; `medium` and `low` mean `standard`. |
| `n` | Only `1`. Send one request per image. |
| `response_format` | Only `b64_json`. |
| `user` | Accepted and not passed on. |

Any other field is refused with `400` and code `unsupported_parameter`, so you never pay for a picture made differently from what you asked.

## Editing

Send the pictures to `POST https://api.katara.com/v1/images/edits` with a `prompt` saying what to change, as `multipart/form-data` (one or more `image` files, as the OpenAI client sends them) or as JSON, with `image` as base64 or a data URL, or a list of them, or `images` as a list of `{"image_url": "data:..."}`. The main image model makes every edit.

- Up to 11 pictures, PNG, JPEG or WebP, each up to 7 MB, and 19 MB for the whole request. Katara does not fetch links or read stored files here.
- `aspect_ratio` and `image_size` work as for a generation; without an aspect ratio the edit keeps the shape of the picture.
- `mask` is refused.
- The reply carries `katara.edit_id`. Send it as `previous_edit_id` with the next edit to keep changing the same picture without sending it again; an edit id is kept for seven days.

## The reply

```json
{
  "created": 1792252800,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "output_format": "png",
  "usage": { "images": 1 },
  "katara": { "cost_usdc": "0.05112", "provider": "managed", "fallback": true }
}
```

`data[0].b64_json` is the image itself, base64-encoded; `output_format` says whether it is `png`, `jpeg` or `webp`. Katara stores nothing you need to fetch afterwards, so save the image from the reply.

A prompt the model refuses to draw is `400 image_refused`, and an expired `previous_edit_id` is `400 edit_expired`. Neither is charged.

## Paying

Every image has one price, known before it is made, the same in USDC and in Account Credits:

| | USDC or credits |
|---|---|
| Main model, `1K` | 0.05112 |
| Main model, `2K` | 0.07128 |
| Main model, `4K` | 0.1464 |
| Each picture sent to an edit | 0.002016 more |
| Lower-cost model | 0.018 |

- A key that pays with USDC is charged in USDC; `katara.cost_usdc` carries the charge.
- A key that pays with Account Credits is charged in credits; `katara.cost_usd` carries the charge.
- Without a key, the request is paid with [x402](https://docs.katara.com/developers/x402.txt). The quote is exactly the image price, with the same schemes and settlement as a chat completion.

Images are made by Katara's own model providers only, never by Katara Community, whatever pays. A request that fails before the image comes back is not charged.

In the chat app, ask Katara Cortex for a picture, or to change one you attached, and it draws it, charged the same way.