> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kymaapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Generation

> Sixteen image models on one async endpoint. Photo, edit, typography, vector, native edit-mode — pay per image, per megapixel, or per quality tier.

Kyma serves sixteen image-generation models behind a single async endpoint. Pick the right model for the output you need; the API shape is identical across all of them.

```bash theme={null}
curl -X POST https://kymaapi.com/v1/images/generations \
  -H "Authorization: Bearer $KYMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "recraft-v4", "prompt": "a cinematic hourglass on a wooden desk, golden hour" }'
```

The endpoint is asynchronous. POST returns `202` with a `job_id` immediately; poll [`GET /v1/jobs/{job_id}`](/api-reference/images-generations) until status is `succeeded`.

## Pick a model

| Model                                                | Best for                                                 |             Cost            | Input           |
| ---------------------------------------------------- | -------------------------------------------------------- | :-------------------------: | --------------- |
| [`recraft-v4`](#recraft-v4)                          | **Default** — design-quality, brand assets, illustration |           \$0.054           | text            |
| [`recraft-v4-pro`](#recraft-v4-pro)                  | Print-ready 4MP design                                   |           \$0.338           | text            |
| [`recraft-v4-vector`](#recraft-v4-vector)            | **Native SVG** — logos, icons, illustration              |           \$0.108           | text            |
| [`recraft-v4-vector-pro`](#recraft-v4-vector-pro)    | 4MP SVG — print-ready vector                             |           \$0.405           | text            |
| [`flux-2-pro`](#flux-2-pro)                          | Photoreal, multi-reference blend, gen+edit               |        $0.041–$0.101        | text + image(s) |
| [`flux-kontext-pro`](#flux-kontext-pro)              | Image edit — inpaint, refine, modify                     |           \$0.054           | text + image    |
| [`ideogram-v3`](#ideogram-v3)                        | Typography, logos, posters, packaging                    |           \$0.108           | text            |
| [`gpt-image-2`](/models/gpt-image-2)                 | **Text-in-image** (multilingual), reasoning composition  | $0.014–$0.297 (per quality) | text + image    |
| [`minimax-image-01`](/models/minimax-image-01)       | Cheapest tier, sub-cent budget                           |           \$0.005           | text            |
| [`imagen-4-fast`](/models/imagen-4-fast)             | Google Imagen — drafts, social previews                  |           \$0.027           | text            |
| [`imagen-4`](/models/imagen-4)                       | Google Imagen — photoreal default                        |           \$0.054           | text            |
| [`imagen-4-ultra`](/models/imagen-4-ultra)           | Google Imagen — print-ready hero                         |           \$0.081           | text            |
| [`nano-banana`](/models/nano-banana)                 | **Edit-mode** — image-in + prompt → image-out            |           \$0.046           | text + image    |
| [`nano-banana-3-flash`](/models/nano-banana-3-flash) | Newer Gemini 3.1 image (preview)                         |           \$0.046           | text + image    |
| [`flux-1.1-ultra`](#flux-1-1-ultra)                  | *Legacy.* Use `flux-2-pro` instead.                      |           \$0.081           | text            |
| [`recraft-v3`](#recraft-v3)                          | *Legacy.* Use `recraft-v4` instead.                      |           \$0.054           | text            |

Prices reflect Kyma's 1.35× markup on the underlying provider cost. See [pricing](/pricing#image-generation), or `GET /v1/pricing` for the live canonical source.

## recraft-v4

**Top of HuggingFace Text-to-Image Arena (#1)** — beats Midjourney V8, DALL-E 3, and FLUX in human preference evaluation. Design-aware composition, lighting, and material rendering. Same price as the previous Recraft V3 default.

```json theme={null}
{
  "model": "recraft-v4",
  "prompt": "isometric vector illustration of a cloud server rack, blue and gold accent",
  "size": "1:1"
}
```

* **Cost**: \$0.054 per image
* **Aspect ratios**: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`
* **n**: up to 4 images per request
* **Best for**: brand illustration, marketing visuals, design-quality default

## recraft-v4-pro

Recraft V4 at 4 megapixels for print-ready or large-scale assets — same design taste as V4 standard, higher resolution.

```json theme={null}
{
  "model": "recraft-v4-pro",
  "prompt": "minimalist coffee bag label, cream background, gold foil typography"
}
```

* **Cost**: \$0.338 per image
* **Output**: up to 4 megapixels
* **Best for**: print, posters, hero campaign visuals, large displays

## recraft-v4-vector

**Native SVG output** — actual paths and structured layers, editable in Figma, Illustrator, or any vector editor. The only generation model on the market shipping true vector files (every other model rasterises and lies about it).

```json theme={null}
{
  "model": "recraft-v4-vector",
  "prompt": "minimalist tech brand mark, abstract wave forming a Greek psi symbol, gold on navy"
}
```

* **Cost**: \$0.108 per image
* **Output**: SVG file (Content-Type: `image/svg+xml`)
* **Best for**: logos, icons, illustration sets, brand systems that need to scale

## recraft-v4-vector-pro

Native SVG at 4 megapixels — for print-ready vectors with finer detail and richer composition.

```json theme={null}
{
  "model": "recraft-v4-vector-pro",
  "prompt": "intricate art-nouveau bookmark illustration with floral flourishes, rendered as clean vector paths"
}
```

* **Cost**: \$0.405 per image
* **Output**: SVG file
* **Best for**: print-ready logos, packaging illustrations, large-scale signage

## flux-2-pro

**BFL's 32B flagship** released November 2025 — 3× larger than Flux 1.1, wins \~2/3 of blind comparisons against the prior generation, \~60% accurate text-in-image. Unifies generation and editing in one model.

Single-reference (image-to-image edit):

```json theme={null}
{
  "model": "flux-2-pro",
  "prompt": "make the sky a stormy sunset",
  "image_url": "https://example.com/source.jpg",
  "size": "16:9"
}
```

Multi-reference blend (up to 10 sources, FLUX.2 Pro's signature feature):

```json theme={null}
{
  "model": "flux-2-pro",
  "prompt": "blend these three style references into one cohesive scene",
  "image_urls": [
    "https://example.com/ref1.jpg",
    "https://example.com/ref2.jpg",
    "https://example.com/ref3.jpg"
  ],
  "size": "16:9"
}
```

The first 6 reference images receive high-fidelity processing; references 7–10 act as supplementary composition guides. Beyond 10 returns `400 too_many_references`.

Text-only is also fully supported — no reference required.

* **Cost**: per megapixel of output, rounded to nearest whole MP. **$0.03** for the first MP + **$0.015** per extra MP, then × 1.35 markup.
  * 1024×1024 → 1 MP → **\$0.041**
  * 1920×1080 → 2 MP → **\$0.061**
  * 2048×2048 → 4 MP → **\$0.101**
* **Best for**: photorealism, multi-source blending, hero shots, unified gen/edit workflows

## flux-kontext-pro

**Image-to-image editor.** Takes an existing image plus a text instruction; returns a modified image. Use for inpainting, prop swaps, background changes, refinement.

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "replace the sky with a stormy sunset",
  "image_url": "https://example.com/source.jpg"
}
```

* **Cost**: \$0.054 per image
* **Requires**: `image_url` (HTTPS URL to the source image). A request without `image_url` returns `400 image_url_required`.

## ideogram-v3

**Text-in-image specialist.** Best model on Kyma for typography, packaging mockups, posters, and logos where readable, accurate text matters.

```json theme={null}
{
  "model": "ideogram-v3",
  "prompt": "minimalist coffee bag label that reads 'KYMA ROAST', cream background, gold foil"
}
```

* **Cost**: \$0.108 per image
* **Strengths**: legible text, brand-safe layouts, packaging design

## flux-1.1-ultra

**Legacy.** Kept for backward compatibility with existing API integrations. New projects should use [`flux-2-pro`](#flux-2-pro) — cheaper at 1MP, higher quality, supports multi-reference.

* **Cost**: \$0.081 per image (flat)
* **Status**: existing API contracts continue to work; not recommended for new code.

## recraft-v3

**Legacy.** Kept for backward compatibility. Use [`recraft-v4`](#recraft-v4) for new projects — same price, top of the HF Arena leaderboard.

* **Cost**: \$0.054 per image
* **Status**: existing API contracts continue to work; not recommended for new code.

## Billing flow

1. POST creates a job and **places a hold** for `estimated_cost` (price × n images, markup applied; or per-MP estimate for FLUX.2 Pro based on requested size).
2. On `succeeded`, the hold is finalized as a `usage` transaction at the actual cost. For FLUX.2 Pro, the actual cost reflects the true output dimensions returned by the provider.
3. On `failed` or `expired`, the hold is fully refunded — you only pay for images you receive.

You can verify the charge on `GET /v1/jobs/{id}`: `charged_amount` is the final billed amount, `estimated_cost` is what was held up front.

## Idempotency

Pass `idempotency_key` to make POST safe to retry. The same `(user_id, idempotency_key)` pair always returns the same job — no duplicate charges, no duplicate generations.

```json theme={null}
{
  "model": "recraft-v4",
  "prompt": "...",
  "idempotency_key": "checkout-flow-card-3"
}
```

## See also

* [`POST /v1/images/generations`](/api-reference/images-generations) — full request/response reference, including `image_urls` multi-reference
* [Pricing — Image generation](/pricing#image-generation) — per-image cost table