---
title: "Media · Generate · Generate AI image"
method: POST
path: "/api/v2/ai-image/generate"
tags: ["aiGeneration"]
---

# Media · Generate · Generate AI image

`POST /api/v2/ai-image/generate`

## Request

- Base URL: `https://api.simplified.com`
- URL: `https://api.simplified.com/api/v2/ai-image/generate`
- Auth: API key in header `Authorization`

Generate an AI image from a prompt, optionally guided by reference
images. One call: POST `{model, parameters}` (`capability` is optional).
It **blocks and returns the final result** — do not call
`getTaskResult`. Use the field names below as-is for every model; the
server adapts the payload to the model you chose. If something does
not fit that model (a ratio it lacks, too many references for the
mode), the error says exactly what to change.

`storage` controls where the result is kept:
- "asset"     — saved to your asset library for reuse (recommended)
- "transient" — temporary, not saved
- "default"   — kept in the image gallery

## Request body

- ImageGenerationV2Request: V2 image generation request with dynamic parameter validation. The parameters field is validated based on model + capability. Call `getModelFields` with `type=image` to discover available models and their required parameter fields.
  - `model` string, required: Model to generate with. A caller that names only a provider ("use OpenAI") takes that family's recommended id, which is the one listed first for the family. Registered ids: `flux.flux-realism` (Flux Pro), `flux.flux-kontext-pro` (Flux Kontext Pro — image editing), `flux.flux-kontext-max` (Flux Kontext Max — image editing), `flux.flux-1.1-pro-ultra` (Flux Pro Ultra), `flux.flux-2-pro` (Flux 2 Pro), `recraft.recraft` (ReCraft V3), `ideogram.ideogram-v3-turbo` (Ideogram V3 Turbo), `ideogram.ideogram-v4` (Ideogram 4.0, text-to-image only), `google.gemini-3.1-flash-image` (Gemini 3.1 Flash Image — recommended for Google), `google.gemini-3-pro-image` (Gemini 3 Pro Image — complex design, dense text, 4K), `google.gemini-3.1-flash-lite-image` (Gemini 3.1 Flash Lite Image), `openai.imgen-2.5-flare` (GPT Image 2.5 Flare — recommended for OpenAI), `openai.imgen-2.5-sunburst` (GPT Image 2.5 Sunburst), `openai.imgen-2` (GPT Image 2 — previous generation, still served), `qwen.qwen-image` (Qwen Image), `qwen.qwen-image-edit` (Qwen Image Edit — image editing), `bytedance.seedream-4` (SeedDream 4), `bytedance.seedream-4.5` (SeedDream 4.5), `bytedance.seedream-5-pro` (Seedream 5 Pro).
  - `capability` 'prompt' | 'reference_image' | 'multiple_images': Generation mode. Optional — when omitted it follows parameters.reference_images: none → prompt, one → reference_image, several → multiple_images. Not where the prompt text goes (that is parameters.prompt). - "prompt" → text-to-image - "reference_image" → image-to-image guided by one reference - "multiple_images" → one image composed from several references. This is not "generate several images" — use parameters.count.
  - `parameters` ImageGenerationV2RequestParameters, required: The generation payload — what the AI model needs to produce the image. Always a nested object: prompt, aspect_ratio, count and reference_images live HERE, never at the top level. Only prompt is required. Use these field names as-is for every model.
    - `prompt` string, required: Plain-English description of the image to generate
    - `aspect_ratio` '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '2:3' | '3:2' | '4:5' | '5:4' | '21:9' | '9:21' | '1:2' | '2:1' | '10:16' | '16:10' | '1:3' | '3:1' | '1:4' | '4:1' | '1:8' | '8:1' | '3:5' | '5:3' | '5:7' | '7:5' | 'match_input_image': Output aspect ratio, one of this list. 1:1, 16:9, 9:16, 4:3 and 3:4 work with every model; if the model you chose does not offer a ratio, the error lists the ones it does. `match_input_image` keeps the reference image's ratio. Never invent a ratio.
    - `count` integer: Number of images to generate (default 1)
    - `negative_prompt` string: What to avoid in the generated image
    - `reference_images` string[]: Reference images: asset UUIDs from this workspace or absolute http(s) URLs. One entry guides an image-to-image generation; several are composed into one image. Prefer the `asset_id` returned by a previous generateImage / createAsset call. A bare filename, a local path, a placeholder, or a UUID from another workspace is rejected; if there are too many for the mode, the error says the limit and which capability to use.
  - `storage` 'default' | 'transient' | 'asset', required: "asset" saves as a persistent TldrAsset (recommended — no expiry, visible in asset library). "transient" generates without saving to database (temporary URL, expires). "default" persists to AiImageArt gallery.

## Response `202`

Generation task accepted — returns task_id (and asset data if storage=asset); the tool waits for it

- unknown

## Other responses

- `400`: Invalid model, capability, or parameters
- `401`: Unauthorized
- `429`: Quota exceeded — no remaining AI credits

---

[API](https://skmtc.dev/simplified/apis/platform.md) - [All operations](https://skmtc.dev/simplified/apis/platform/llms.txt) - [OpenAPI document](https://skmtc.dev/simplified/apis/platform/revisions/0815a1ba1e4e?raw)