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.

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

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