--- title: "Layerize the text in an image" method: POST path: "/v2/design/layerize/ideogram-3" tags: ["design"] --- # Layerize the text in an image `POST /v2/design/layerize/ideogram-3` Decompose a flat image into an editable design: the text in the image is detected, erased from the image, and returned as positioned text blocks with matched fonts, sizes, and colors, alongside a text-free base image. Supply the source either as an `image_asset_identifier` reference (an image already stored with Ideogram) or as raw `image` bytes (multipart requests only). Provide exactly one of the two forms; supplying both, or neither, is rejected with a 400. A `prompt` describing the image can guide text detection; when omitted, detection runs on the image alone. By default the request blocks until layerization is complete and returns the result in `data`. Set `async` to true to return immediately after the request is accepted, then poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. Supplying a `webhook_url` makes the request asynchronous whatever `async` says: the response returns as soon as the request is accepted, and the finished result is POSTed to that URL. ## Query parameters - `dry_run` boolean ## Request body - LayerizeDesignIdeogramV3Request — Supply the source image either as an `image_asset_identifier` reference or (multipart requests only) as raw `image` bytes. Provide exactly one of the two forms; supplying both, or neither, is rejected with a 400. - `image_asset_identifier` AssetIdentifier — An identifier for an ideogram asset. - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required - `asset_id` string, required - `image` string, binary — The source image to layerize (max size 50MB), as raw bytes; only common image formats such as JPEG, PNG, and WEBP are supported. Multipart requests only. Provide exactly one of `image_asset_identifier` or `image`. - `prompt` string, nullable — A description of the image, used to guide text detection. When omitted, detection runs on the image alone. - `seed` integer — Random seed. Set for reproducible generation. - `font_candidate_files` string[] — Candidate font files to make available for text style matching. Supported formats .ttf, .otf, .woff, .woff2 (max 5MB each, maximum 5 files). Multipart requests only. - `async` boolean — When false (the default), the request blocks until layerization is complete and returns the result in `data`. When true, the request returns as soon as it is accepted; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. - `webhook_url` string, uri — 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. - `private` boolean, nullable — When true or omitted, the output is kept private to your account. Set to false to publish the output to the public feed. Enterprise accounts always generate privately. - `target_collection_id` string — A collection you can write to, by its URL-safe base64 collection id. The output is added to it when the request completes. ## Response `200` The layerized design (synchronous requests), or an acknowledgement to poll with `GET /v1/generations/{generation_id}` (`async` requests). - LayerizeDesignIdeogramV3Response — Response returned by `POST /v2/design/layerize/ideogram-3`. Synchronous requests (the default) include the layerized design in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v1/generations/{generation_id}` using the returned `generation_id`. The seed reports the value the request resolved to when the caller left it unset. - `generation_id` string, required — URL-safe base64 ID of the accepted generation. Accepted by the `GET /v1/generations/{generation_id}` polling endpoint. - `data` LayerizedImageObject[] — The layerized design. Present only for synchronous requests (`async` omitted or false). - `object_type` 'layerized_image', required — Discriminates layerized results from other generation output types. - `url` string, uri, nullable — The direct link to the design image with its text intact. Empty when the image did not pass safety checks. - `base_image_url` string, uri, nullable — The direct link to the base image with all detected text removed. Empty when the image did not pass safety checks. - `resolution` string, required — The resolution of the design, formatted as "WIDTHxHEIGHT". - `is_image_safe` boolean, required — Whether the image passed safety checks. If false, the image links are empty. - `seed` integer, required — Random seed. Set for reproducible generation. - `text_blocks` DetectedTextBlock[], required — Flat list of detected text regions in the design. - `x` integer, required — X coordinate in pixels from the top-left corner. - `y` integer, required — Y coordinate in pixels from the top-left corner. - `width` integer, required — Width of the text region in pixels. - `height` integer, required — Height of the text region in pixels. - `text` string, required — The detected text content. Line breaks are represented as \n. - `alignment` 'left' | 'center' | 'right', required — Detected text alignment. - `angle` number, float — Rotation angle in degrees (clockwise). Defaults to 0. - `font_name` string, nullable — Best-matching font name from the font library. - `font_alternatives` string[], nullable — Alternative font matches, ranked by similarity. - `font_size` integer, nullable — Detected font size in points. - `line_height` number, float, nullable — Line height multiplier (e.g., 1.2). - `color` string, nullable — Detected text color in hex format. - `formatting` string[], required — Detected text formatting effects. - `role` 'heading' | 'subheading' | 'body' | 'caption', nullable — Inferred typographic role of this text block. - `seed` integer, required — Random seed. Set for reproducible generation. ## Other responses - `400` — Invalid input provided. - `401` — Unauthorized. - `402` — Insufficient credits or quota. - `403` — Not authorized to layerize images. - `404` — The referenced source asset was not found. - `429` — Too many requests. - `500` — Internal server error. - `503` — The endpoint is temporarily unavailable. ## Changes - **2026-09-19** `4e95197be44a` — 1 info - endpoint added [Change history](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/changes/v2/design/layerize/ideogram-3/post.md) --- [API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/revisions/4e95197be44a?raw)