> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.simplified.com/api-reference/platform/ai-generation/generate-image/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server. # Media · Generate · Generate AI image POST https://api.simplified.com/api/v2/ai-image/generate Content-Type: application/json 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 Reference: https://docs.simplified.com/api-reference/platform/ai-generation/generate-image ## Authentication - `Authorization` header (required) (prefixed with ` Api-Key `) — Header authentication of the form `Api-Key ` - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an ImageGenerationV2Request. - `model` (string, required, default: google.gemini-3.1-flash-image) — 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). - `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. - `storage` (enum, required, default: asset) — "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. - Allowed values: `default`, `transient`, `asset` - `capability` (enum, optional) — 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. - Allowed values: `prompt`, `reference_image`, `multiple_images` ## Response ### 202 Generation task accepted — returns task_id (and asset data if storage=asset); the tool waits for it - `any` ## Errors ### 400 Bad Request Error Invalid model, capability, or parameters - `any` ### 401 Unauthorized Error Unauthorized - `any` ### 429 Too Many Requests Error Quota exceeded — no remaining AI credits - `any` ## Types ### ImageGenerationV2RequestParameters 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` (enum, optional) — 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. - Allowed values: `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` - `count` (integer, optional) — Number of images to generate (default 1) - `negative_prompt` (string, optional) — What to avoid in the generated image - `reference_images` (list of string, optional) — 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. ## Examples **Request** ```json { "model": "google.gemini-3.1-flash-image", "parameters": { "prompt": "A professional product photo of a sleek laptop on a wooden desk", "aspect_ratio": "16:9" }, "storage": "asset", "capability": "prompt" } ``` **SDK Code** ```python AI Generation_generateImage_example import requests url = "https://api.simplified.com/api/v2/ai-image/generate" payload = { "model": "google.gemini-3.1-flash-image", "parameters": { "prompt": "A professional product photo of a sleek laptop on a wooden desk", "aspect_ratio": "16:9" }, "storage": "asset", "capability": "prompt" } headers = { "Authorization": "Api-Key ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript AI Generation_generateImage_example const url = 'https://api.simplified.com/api/v2/ai-image/generate'; const options = { method: 'POST', headers: {Authorization: 'Api-Key ', 'Content-Type': 'application/json'}, body: '{"model":"google.gemini-3.1-flash-image","parameters":{"prompt":"A professional product photo of a sleek laptop on a wooden desk","aspect_ratio":"16:9"},"storage":"asset","capability":"prompt"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go AI Generation_generateImage_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.simplified.com/api/v2/ai-image/generate" payload := strings.NewReader("{\n \"model\": \"google.gemini-3.1-flash-image\",\n \"parameters\": {\n \"prompt\": \"A professional product photo of a sleek laptop on a wooden desk\",\n \"aspect_ratio\": \"16:9\"\n },\n \"storage\": \"asset\",\n \"capability\": \"prompt\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Api-Key ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby AI Generation_generateImage_example require 'uri' require 'net/http' url = URI("https://api.simplified.com/api/v2/ai-image/generate") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Api-Key ' request["Content-Type"] = 'application/json' request.body = "{\n \"model\": \"google.gemini-3.1-flash-image\",\n \"parameters\": {\n \"prompt\": \"A professional product photo of a sleek laptop on a wooden desk\",\n \"aspect_ratio\": \"16:9\"\n },\n \"storage\": \"asset\",\n \"capability\": \"prompt\"\n}" response = http.request(request) puts response.read_body ``` ```java AI Generation_generateImage_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.simplified.com/api/v2/ai-image/generate") .header("Authorization", "Api-Key ") .header("Content-Type", "application/json") .body("{\n \"model\": \"google.gemini-3.1-flash-image\",\n \"parameters\": {\n \"prompt\": \"A professional product photo of a sleek laptop on a wooden desk\",\n \"aspect_ratio\": \"16:9\"\n },\n \"storage\": \"asset\",\n \"capability\": \"prompt\"\n}") .asString(); ``` ```php AI Generation_generateImage_example request('POST', 'https://api.simplified.com/api/v2/ai-image/generate', [ 'body' => '{ "model": "google.gemini-3.1-flash-image", "parameters": { "prompt": "A professional product photo of a sleek laptop on a wooden desk", "aspect_ratio": "16:9" }, "storage": "asset", "capability": "prompt" }', 'headers' => [ 'Authorization' => 'Api-Key ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp AI Generation_generateImage_example using RestSharp; var client = new RestClient("https://api.simplified.com/api/v2/ai-image/generate"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Api-Key "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model\": \"google.gemini-3.1-flash-image\",\n \"parameters\": {\n \"prompt\": \"A professional product photo of a sleek laptop on a wooden desk\",\n \"aspect_ratio\": \"16:9\"\n },\n \"storage\": \"asset\",\n \"capability\": \"prompt\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift AI Generation_generateImage_example import Foundation let headers = [ "Authorization": "Api-Key ", "Content-Type": "application/json" ] let parameters = [ "model": "google.gemini-3.1-flash-image", "parameters": [ "prompt": "A professional product photo of a sleek laptop on a wooden desk", "aspect_ratio": "16:9" ], "storage": "asset", "capability": "prompt" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.simplified.com/api/v2/ai-image/generate")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```