> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://developer.ideogram.ai/v2/llms.txt > - v1: https://developer.ideogram.ai/v1/llms.txt > 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 with a custom Ideogram 3.0 model POST https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model Content-Type: multipart/form-data Generate images with a custom Ideogram 3.0 model that you or your organization can access, selected by `custom_model_uri`. Returns results directly by default; set `async` or supply a `webhook_url` to get a `generation_id` and poll `GET /v2/generations/{generation_id}`. Reference: https://developer.ideogram.ai/api-reference/images/generate/ideogram-3-custom-model ## Authentication - `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\" ## Request ### Query parameters - `dry_run` (boolean, optional, default: false) — When true, the request is validated and priced but not run: nothing is generated, stored, or billed, and no safety review is performed. The response is a `PriceQuote` object instead of the usual response for this endpoint. Send exactly the request you would send to generate, so the quote reflects the same options. ### Body (multipart/form-data) This endpoint expects a multipart form with multiple files. - `prompt` (string, required) — The prompt to generate images from. - `custom_model_uri` (string, required) — The custom model URI, in the form `model//version/`. You or your organization must have access to the model. The model determines which rendering speeds are supported and whether backgrounds are removed automatically. - `transparent_background` (boolean, optional) — Remove the background after generation and return transparent PNG images. Included in the custom model generation price at no extra charge. When false, the model's automatic background removal behavior still applies. - `negative_prompt` (string, optional) — Description of what to exclude from the images. The prompt takes precedence over the negative prompt. - `seed` (integer, optional) — Random seed. Set for reproducible generation. - `resolution` (enum, optional) - `aspect_ratio` (enum, optional) - `rendering_speed` (enum, optional) — The rendering speed to use. When omitted, a speed supported by the custom model is used. - `magic_prompt` (enum, optional) — Controls magic prompt (automatic prompt rewriting). Defaults to `auto`. - `num_images` (integer, optional) — The number of images to generate. - `color_palette` (IdeogramColorPalette, optional) - `style_codes` (list of string, optional) — A list of 8-character hexadecimal codes representing the style of the image. Refer to each endpoint for supported combinations with style types, presets, and reference images. - `style_preset` (enum, optional) — A predefined style preset to apply to the generated images. Cannot be combined with style codes or style references. - `style_reference_images` (files, optional) — Images to use as style references (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only. - `enable_copyright_detection` (boolean, optional) — Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with `is_image_safe: false`. - `async` (boolean, optional) — When false (the default), the request waits until the images are ready and returns them in `data`. When true, the request returns as soon as it is accepted; poll `GET /v2/generations/{generation_id}` with the returned `generation_id` for the result. - `webhook_url` (string, optional) — HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a JSON POST to this URL once all images for the request have finished generating. The body mirrors the synchronous generate response: `request_id`, `created`, and a `data` array containing every generated image (`url`, `prompt`, `resolution`, `seed`, `is_image_safe`). Each delivery is signed with Ed25519 and verifiable against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS; private and loopback hosts and the cloud metadata service are rejected. ## Response ### 200 The generated images (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests). - `generation_id` (string, required) — URL-safe base64 ID of the generation. Use it to poll `GET /v2/generations/{generation_id}`. - `seed` (integer, required) — Random seed. Set for reproducible generation. - `data` (list of GeneratedImageObject, optional) — The generated images, in generation order. Present only for synchronous requests (`async` omitted or false). ## Errors ### 400 Bad Request Error Invalid input or an unsupported model option. - `any` ### 401 Unauthorized Error Unauthorized. - `any` ### 402 Payment Required Error Insufficient credits or quota. - `error` (string, required) — A message describing why the generation request was rejected. - `reject_reason` (enum, required) — The account or usage limit that rejected a generation request. - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit` - `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`. - `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`. - Allowed values: `fast`, `slow` ### 403 Forbidden Error The custom model does not exist or is not accessible to this user or organization. - `any` ### 404 Not Found Error A requested resource was not found. - `any` ### 422 Unprocessable Entity Error The prompt did not pass safety checks. - `any` ### 429 Too Many Requests Error Too many requests. - `error` (string, required) — A message describing why the generation request was rejected. - `reject_reason` (enum, required) — The account or usage limit that rejected a generation request. - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit` - `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`. - `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`. - Allowed values: `fast`, `slow` ### 500 Internal Server Error Internal server error. - `any` ### 503 Service Unavailable Error The endpoint is temporarily unavailable. - `any` ## Types ### GeneratedImageObject One generated output image. - `prompt` (string, required) — The final prompt the image was generated from. - `resolution` (string, required) — The resolution of the generated image, formatted as "WIDTHxHEIGHT". - `is_image_safe` (boolean, required) — Whether the image passed safety checks. If false, `url` is empty. - `seed` (integer, required) — Random seed. Set for reproducible generation. - `url` (string, optional, nullable) — The direct link to the generated image. Empty when the image did not pass safety checks. ## Examples **Request** ```json { "custom_model_uri": "model/my-custom-model/version/1", "prompt": "string", "style_reference_images": [] } ``` **Response** ```json { "generation_id": "generation_id", "seed": 12345, "data": [ { "prompt": "prompt", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://openapi-generator.tech" }, { "prompt": "prompt", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://openapi-generator.tech" } ] } ``` **SDK Code** ```python import requests url = "https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model" payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_model_uri\"\r\n\r\nmodel/my-custom-model/version/1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"transparent_background\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n" headers = { "Api-Key": "", "Content-Type": "multipart/form-data; boundary=---011000010111000001101001" } response = requests.post(url, data=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model'; const form = new FormData(); form.append('aspect_ratio', ''); form.append('async', ''); form.append('color_palette', ''); form.append('custom_model_uri', 'model/my-custom-model/version/1'); form.append('enable_copyright_detection', ''); form.append('magic_prompt', ''); form.append('negative_prompt', ''); form.append('num_images', ''); form.append('prompt', 'string'); form.append('rendering_speed', ''); form.append('resolution', ''); form.append('seed', ''); form.append('style_codes', ''); form.append('style_preset', ''); form.append('transparent_background', ''); form.append('webhook_url', ''); const options = {method: 'POST', headers: {'Api-Key': ''}}; options.body = form; 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/v2/image/generate/ideogram-3-custom-model" payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_model_uri\"\r\n\r\nmodel/my-custom-model/version/1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"transparent_background\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Api-Key", "") 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/v2/image/generate/ideogram-3-custom-model") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Api-Key"] = '' request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_model_uri\"\r\n\r\nmodel/my-custom-model/version/1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"transparent_background\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\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/v2/image/generate/ideogram-3-custom-model") .header("Api-Key", "") .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_model_uri\"\r\n\r\nmodel/my-custom-model/version/1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"transparent_background\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n") .asString(); ``` ```php request('POST', 'https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model', [ 'multipart' => [ [ 'name' => 'custom_model_uri', 'contents' => 'model/my-custom-model/version/1' ], [ 'name' => 'prompt', 'contents' => 'string' ] ] 'headers' => [ 'Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model"); var request = new RestRequest(Method.POST); request.AddHeader("Api-Key", ""); request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"aspect_ratio\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"color_palette\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"custom_model_uri\"\r\n\r\nmodel/my-custom-model/version/1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"magic_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"negative_prompt\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"rendering_speed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"resolution\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_codes\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"style_preset\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"transparent_background\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Api-Key": ""] let parameters = [ [ "name": "aspect_ratio", "value": ], [ "name": "async", "value": ], [ "name": "color_palette", "value": ], [ "name": "custom_model_uri", "value": "model/my-custom-model/version/1" ], [ "name": "enable_copyright_detection", "value": ], [ "name": "magic_prompt", "value": ], [ "name": "negative_prompt", "value": ], [ "name": "num_images", "value": ], [ "name": "prompt", "value": "string" ], [ "name": "rendering_speed", "value": ], [ "name": "resolution", "value": ], [ "name": "seed", "value": ], [ "name": "style_codes", "value": ], [ "name": "style_preset", "value": ], [ "name": "transparent_background", "value": ], [ "name": "webhook_url", "value": ] ] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v2/image/generate/ideogram-3-custom-model")! 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() ```