---
url: /orchestration/recipes/mai-image.md
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# MAI Image 2.5 image generation

MAI Image 2.5 is Microsoft's text-to-image model, hosted through FAL. The orchestrator exposes it as a single `engine: "fal"`, `model: "maiImage"`, `operation: "createImage"` entry — text-to-image only, with no editing, seed, or style-reference inputs.

**Default choice**: leave `aspectRatio` at `"auto"` and let the model pick a composition-appropriate ratio, or pin one of the eleven supported ratios when you need a specific shape.

## Text-to-image

```http
POST https://orchestration.civitai.com/v2/consumer/workflows?wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "fal",
      "model": "maiImage",
      "operation": "createImage",
      "prompt": "A photorealistic portrait of a woman with flowers in her hair, golden hour lighting",
      "aspectRatio": "1:1"
    }
  }]
}
```

### Parameters

| Field | Required | Default | Notes |
|-------|----------|---------|-------|
| `prompt` | ✅ | — | 3–5000 characters. Natural-language prompts work well. |
| `aspectRatio` | | `"auto"` | One of `auto` / `21:9` / `16:9` / `3:2` / `4:3` / `5:4` / `1:1` / `4:5` / `3:4` / `2:3` / `9:16`. `auto` lets the model choose. MAI returns a fixed resolution per ratio — no width/height. |
| `quantity` | | `1` | `1`–`4`. MAI bills each image separately; quantities > 1 fan out to parallel FAL calls. |
| `outputFormat` | | `"jpeg"` | `jpeg` / `png` / `webp`. |

MAI Image does **not** accept negative prompts, seeds, LoRAs, style references, or explicit width/height — use the [Krea](https://developer.civitai.com/orchestration/recipes/krea.md), [Qwen](https://developer.civitai.com/orchestration/recipes/qwen.md), or [Flux 2](https://developer.civitai.com/orchestration/recipes/flux2.md) recipes if you need any of those.

## Auto aspect ratio

Omit `aspectRatio` (or set it to `"auto"`) to let MAI choose a ratio that suits the prompt:

```json
{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "fal",
      "model": "maiImage",
      "operation": "createImage",
      "prompt": "A majestic dragon soaring through clouds at sunset, highly detailed, fantasy art",
      "aspectRatio": "auto"
    }
  }]
}
```

## Batch generation

Set `quantity` up to `4` for multiple images from one step. Each image is a separate FAL call (and a separate charge), run in parallel:

```json
{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "fal",
      "model": "maiImage",
      "operation": "createImage",
      "prompt": "An astronaut riding a horse on Mars, dramatic lighting",
      "aspectRatio": "9:16",
      "quantity": 4
    }
  }]
}
```

## Reading the result

Standard `imageGen` output: an `images[]` array, one entry per `quantity` ([shape and URL expiry](https://developer.civitai.com/orchestration/recipes.md#reading-results)).

## Runtime

Single images typically land well inside the `wait=60` long-poll window, so a single `wait=60` POST covers the common case. A `quantity: 4` batch fans out to parallel calls but can still outlast your HTTP client's timeout on busy FAL queues — submit those with `wait=0` and poll, or register a webhook.

## Cost

Preview the exact charge with `whatif=true` ([Payments (Buzz)](https://developer.civitai.com/orchestration/guide/submitting-work.md#payments-buzz)).

MAI bills a flat rate per generated image:

```
total = 65 × quantity
```

| Shape | Buzz |
|-------|------|
| Default (`quantity: 1`) | **65** |
| Batch of 4 (`quantity: 4`) | 260 |

Aspect ratio and output format don't affect MAI's Buzz price — the provider charges flat per image.

## Troubleshooting

Timeouts, moderation blocks and expired blob URLs: see [Common troubleshooting](https://developer.civitai.com/orchestration/recipes.md#common-troubleshooting).

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `400` with "prompt" length error | Prompt under 3 or over 5000 characters | Keep the prompt within 3–5000 characters. |
| `400` with "aspectRatio must be one of" | Invalid aspect ratio | Pick one of the listed ratios (or `auto`) — MAI doesn't accept width/height. |
| `400` with "quantity" range error | `quantity` outside `1`–`4` | MAI caps batches at 4 images per step. |

## Related

* [`SubmitWorkflow`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md) · [`GetWorkflow`](https://developer.civitai.com/orchestration/reference/operations/GetWorkflow.md)
* [Krea v2](https://developer.civitai.com/orchestration/recipes/krea.md) / [Qwen](https://developer.civitai.com/orchestration/recipes/qwen.md) image generation — sibling FAL-hosted text-to-image families (Qwen adds editing and LoRAs)
* [Flux 2](https://developer.civitai.com/orchestration/recipes/flux2.md) / [Flux 1](https://developer.civitai.com/orchestration/recipes/flux1.md) image generation — open-weights families with LoRA support
* [Image upscaling](https://developer.civitai.com/orchestration/recipes/image-upscaler.md) — chain after `imageGen` for higher-res output
* [Prompt enhancement](https://developer.civitai.com/orchestration/recipes/prompt-enhancement.md) — LLM-rewrite a prompt before feeding it in via `$ref`
* Full parameter catalog: `MaiImageCreateFalImageGenInput` in the [API reference](https://developer.civitai.com/orchestration/reference.md)
* [`imageGen` OpenAPI spec](https://orchestration.civitai.com/v2/consumer/recipes/imageGen/openapi.yaml)