> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ideogram.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server. # Generate (legacy) POST https://api.ideogram.ai/generate Content-Type: application/json Generates images synchronously based on a given prompt and optional parameters. Images links are available for a limited period of time; if you would like to keep the image, you must download it. Reference: https://developer.ideogram.ai/v1/api-reference/legacy-endpoints/generate ## Authentication - `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\" ## Request ### Body (application/json) This endpoint expects a GenerateImageRequest. - `image_request` (ImageRequest, required) ## Response ### 200 Image(s) generated successfully. - `created` (datetime, required) — The time the request was created. - `request_id` (string, optional) — URL-safe base64 ID of the sampling request. Present when the caller supplied `webhook_url` and the request was accepted for async delivery; in that case `data` is omitted and the generated images will be POSTed to the customer's `webhook_url` when ready. - `data` (list of ImageObject, optional) — A list of ImageObjects that contain the generated image(s). ## Errors ### 400 Bad Request Error Invalid input provided. - `any` ### 401 Unauthorized Error Not authorized to generate an image. - `any` ### 422 Unprocessable Entity Error Prompt failed the safety check. - `error` (string, required) ### 429 Too Many Requests Error Too many requests. - `any` ## Types ### ImageRequest - `prompt` (string, required) — The prompt to use to generate the image. - `aspect_ratio` (enum, optional) — (Cannot be used in conjunction with resolution) The aspect ratio to use for image generation, which determines the image's resolution. Defaults to ASPECT_1_1. - Allowed values: `ASPECT_10_16`, `ASPECT_16_10`, `ASPECT_9_16`, `ASPECT_16_9`, `ASPECT_3_2`, `ASPECT_2_3`, `ASPECT_4_3`, `ASPECT_3_4`, `ASPECT_1_1`, `ASPECT_1_3`, `ASPECT_3_1` - `model` (enum, optional, default: V_2) — The model used to generate an image or edit one. /generate and /remix supports all model types, however, /edit is only supported for V_2 and V_2_TURBO. - Allowed values: `V_1`, `V_1_TURBO`, `V_2`, `V_2_TURBO`, `V_2A`, `V_2A_TURBO`, `AUTO` - `magic_prompt_option` (enum, optional) — Determine if MagicPrompt should be used in generating the request or not. - Allowed values: `AUTO`, `ON`, `OFF` - `seed` (integer, optional) — Random seed. Set for reproducible generation. - `style_type` (enum, optional) — The style type to generate with; this is only applicable for models V_2 and above and should not be specified for model versions V_1. - Allowed values: `AUTO`, `GENERAL`, `FICTION`, `REALISTIC`, `DESIGN`, `RENDER_3D`, `ANIME` - `negative_prompt` (string, optional) — Only available for model versions V_1, V_1_TURBO, V_2 and V_2_TURBO. Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt. - `num_images` (integer, optional, default: 1) — The number of images to generate. - `resolution` (enum, optional) — (For model_version for 2.0 only, cannot be used in conjunction with aspect_ratio) The resolution to use for image generation, represented in width x height. If not specified, defaults to using aspect_ratio. - Allowed values: `RESOLUTION_512_1536`, `RESOLUTION_576_1408`, `RESOLUTION_576_1472`, `RESOLUTION_576_1536`, `RESOLUTION_640_1024`, `RESOLUTION_640_1344`, `RESOLUTION_640_1408`, `RESOLUTION_640_1472`, `RESOLUTION_640_1536`, `RESOLUTION_704_1152`, `RESOLUTION_704_1216`, `RESOLUTION_704_1280`, `RESOLUTION_704_1344`, `RESOLUTION_704_1408`, `RESOLUTION_704_1472`, `RESOLUTION_720_1280`, `RESOLUTION_736_1312`, `RESOLUTION_768_1024`, `RESOLUTION_768_1088`, `RESOLUTION_768_1152`, `RESOLUTION_768_1216`, `RESOLUTION_768_1232`, `RESOLUTION_768_1280`, `RESOLUTION_768_1344`, `RESOLUTION_832_960`, `RESOLUTION_832_1024`, `RESOLUTION_832_1088`, `RESOLUTION_832_1152`, `RESOLUTION_832_1216`, `RESOLUTION_832_1248`, `RESOLUTION_864_1152`, `RESOLUTION_896_960`, `RESOLUTION_896_1024`, `RESOLUTION_896_1088`, `RESOLUTION_896_1120`, `RESOLUTION_896_1152`, `RESOLUTION_960_832`, `RESOLUTION_960_896`, `RESOLUTION_960_1024`, `RESOLUTION_960_1088`, `RESOLUTION_1024_640`, `RESOLUTION_1024_768`, `RESOLUTION_1024_832`, `RESOLUTION_1024_896`, `RESOLUTION_1024_960`, `RESOLUTION_1024_1024`, `RESOLUTION_1088_768`, `RESOLUTION_1088_832`, `RESOLUTION_1088_896`, `RESOLUTION_1088_960`, `RESOLUTION_1120_896`, `RESOLUTION_1152_704`, `RESOLUTION_1152_768`, `RESOLUTION_1152_832`, `RESOLUTION_1152_864`, `RESOLUTION_1152_896`, `RESOLUTION_1216_704`, `RESOLUTION_1216_768`, `RESOLUTION_1216_832`, `RESOLUTION_1232_768`, `RESOLUTION_1248_832`, `RESOLUTION_1280_704`, `RESOLUTION_1280_720`, `RESOLUTION_1280_768`, `RESOLUTION_1280_800`, `RESOLUTION_1312_736`, `RESOLUTION_1344_640`, `RESOLUTION_1344_704`, `RESOLUTION_1344_768`, `RESOLUTION_1408_576`, `RESOLUTION_1408_640`, `RESOLUTION_1408_704`, `RESOLUTION_1472_576`, `RESOLUTION_1472_640`, `RESOLUTION_1472_704`, `RESOLUTION_1536_512`, `RESOLUTION_1536_576`, `RESOLUTION_1536_640` - `color_palette` (ColorPaletteWithPresetNameOrMembers, optional) — A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members). Not supported by V_1, V_1_TURBO, V_2A and V_2A_TURBO models. ### ImageObject - `prompt` (string, required) — The prompt used for the generation. This may be different from the original prompt. - `resolution` (string, required) — The resolution of the final image. - `is_image_safe` (boolean, required) — Whether this request passes safety checks. If false, the url field will be empty. - `seed` (integer, required) — Random seed. Set for reproducible generation. - `url` (string, optional, nullable) — The direct link to the image generated. - `upscaled_resolution` (string, optional) — Output resolution, only used if operations alters image dimensions, such as upscale, crop etc. - `style_type` (enum, optional) — The style type to generate with; this is only applicable for models V_2 and above and should not be specified for model versions V_1. - Allowed values: `AUTO`, `GENERAL`, `FICTION`, `REALISTIC`, `DESIGN`, `RENDER_3D`, `ANIME` ### ColorPaletteWithPresetNameOrMembers A color palette for generation, must EITHER be specified via one of the presets (name) or explicitly via hexadecimal representations of the color with optional weights (members). Not supported by V_1, V_1_TURBO, V_2A and V_2A_TURBO models. ### ColorPaletteWithPresetName - `name` (enum, required) — A color palette preset value. - Allowed values: `EMBER`, `FRESH`, `JUNGLE`, `MAGIC`, `MELON`, `MOSAIC`, `PASTEL`, `ULTRAMARINE` ### ColorPaletteWithMembers A color palette represented only via its members. Cannot be used in conjunction with preset name. - `members` (list of ColorPaletteMember, required) — A list of ColorPaletteMembers that define the color palette. Each color palette member consists of a required color hex and an optional weight between 0.05 and 1.0 (inclusive). It is recommended that these weights descend from highest to lowest for the color hexes provided. ### ColorPaletteMember A member of a color palette. - `color_hex` (string, required) — The hexadecimal representation of the color with an optional chosen weight. - `color_weight` (double, optional) — The weight of the color in the color palette. ## Examples **Request** ```json { "image_request": { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "model": "V_2", "magic_prompt_option": "AUTO" } } ``` **Response** ```json { "created": "2024-01-15T09:30:00Z", "request_id": "request_id", "data": [ { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g", "upscaled_resolution": "4096x4096", "style_type": "REALISTIC" } ] } ``` **SDK Code** ```python import requests url = "https://api.ideogram.ai/generate" payload = { "image_request": { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "model": "V_2", "magic_prompt_option": "AUTO" } } headers = { "Api-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.ideogram.ai/generate'; const options = { method: 'POST', headers: {'Api-Key': '', 'Content-Type': 'application/json'}, body: '{"image_request":{"prompt":"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.","aspect_ratio":"ASPECT_10_16","model":"V_2","magic_prompt_option":"AUTO"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ideogram.ai/generate" payload := strings.NewReader("{\n \"image_request\": {\n \"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\",\n \"aspect_ratio\": \"ASPECT_10_16\",\n \"model\": \"V_2\",\n \"magic_prompt_option\": \"AUTO\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("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 require 'uri' require 'net/http' url = URI("https://api.ideogram.ai/generate") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Api-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"image_request\": {\n \"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\",\n \"aspect_ratio\": \"ASPECT_10_16\",\n \"model\": \"V_2\",\n \"magic_prompt_option\": \"AUTO\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ideogram.ai/generate") .header("Api-Key", "") .header("Content-Type", "application/json") .body("{\n \"image_request\": {\n \"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\",\n \"aspect_ratio\": \"ASPECT_10_16\",\n \"model\": \"V_2\",\n \"magic_prompt_option\": \"AUTO\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.ideogram.ai/generate', [ 'body' => '{ "image_request": { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "model": "V_2", "magic_prompt_option": "AUTO" } }', 'headers' => [ 'Api-Key' => '', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ideogram.ai/generate"); var request = new RestRequest(Method.POST); request.AddHeader("Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"image_request\": {\n \"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\",\n \"aspect_ratio\": \"ASPECT_10_16\",\n \"model\": \"V_2\",\n \"magic_prompt_option\": \"AUTO\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Api-Key": "", "Content-Type": "application/json" ] let parameters = ["image_request": [ "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "model": "V_2", "magic_prompt_option": "AUTO" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/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() ```