Image generation

One endpoint, one body, one receipt. Every run is priced before it starts, and the price you were quoted is the price you are charged.

Endpoint

POST /api/generate

Authenticate as described in Authentication. The same endpoint serves images, video and chat — kind decides which.

Request body

Field	Type	Required	Notes
`kind`	string	yes	Use `"image"`.
`prompt`	string	yes	Checked by the safety guard before anything is priced or run.
`model`	string	yes	One of the ids below. An unknown id is refused with `unknown_cost` — nothing runs, nothing is charged.
`quality`	string	no	Model-specific. Falls back to the model default.
`aspect`	string	no	For example `"16:9"` or `"9:16"`. Snapped server-side to what the model actually supports.

The field is quality, not resolution. A body carrying resolution is accepted, but the value is ignored and the model default is used instead — silently. If your output looks different from what you asked for, check this first.

Models and what they cost

Read straight from the pricing table the billing code uses, so this list cannot drift.

Model id	Also accepted as	Credits per image
`image-flux`	`flux`	3
`kie-z-image`	—	3
`kie-seedream-4`	—	4
`image-flux-dev`	—	5
`image-qwen`	—	5
`gpt-image-1`	`gpt-image`	6
`image-seedream-3`	—	6
`image-nano-banana`	—	8
`image-nano-banana-2`	—	8
`image-recraft-v3`	—	9
`image-flux-ultra`	—	12
`image-ideogram-v2`	—	15
`image-nano-pro`	`nano-pro`	17
`gpt-image-1-high`	—	17
`image-gpt-high`	`gpt-high`	22

Example

curl https://katama.ai/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "prompt": "a small red paper crane on a plain grey table, soft light",
    "model": "flux"
  }'

Response

The call returns a generation record. When it comes back with status: "succeeded", outputUrl is ready to fetch.

{
  "generation": {
    "id": "dabb8909-369e-4118-9b89-186a3da81c5a",
    "kind": "image",
    "model": "flux",
    "status": "succeeded",
    "outputUrl": "https://…/PPhtLdquFOEu.jpg",
    "creditsCharged": 3,
    "error": null
  }
}

A longer run may return status: "queued" or "running" first. Poll the generation until it settles. While it runs, the credits sit in a hold; the hold is released if the run fails, so a failed generation costs nothing.

Errors worth handling

Code	HTTP	What it means
`unknown_cost`	400	No price is defined for that model id. Nothing ran.
`insufficient_credits`	402	The quoted price exceeds the balance. Top up, then retry.
`unauthorized`	401	No valid session or API key — see Authentication.

Next: Video generation · Plans & credits