--- title: "Generate with Ideogram 4.0 (Transparent Background)" method: POST path: "/v1/ideogram-v4/generate-transparent" tags: ["generate"] --- # Generate with Ideogram 4.0 (Transparent Background) `POST /v1/ideogram-v4/generate-transparent` Generates images with a transparent background synchronously using the Ideogram 4.0 model. The result is delivered as a PNG with an alpha channel. All Ideogram 4.0 aspect ratios are supported, including `AUTO`, which lets the model select the most suitable ratio from the prompt. `output_resolution` selects the delivered resolution tier. Tiers are total-pixel budgets: wide and tall aspect ratios keep the same pixel budget as the square of the named size, so a single dimension may exceed it. The response reports the final delivered resolution. Image links are available for a limited period of time; if you would like to keep the image, you must download it. ## Request body - GenerateTransparentImageRequestV4 — Request body for Ideogram 4.0 transparent-background image generation. Supply exactly one of `text_prompt` or `json_prompt`. When `text_prompt` is supplied, magic-prompt is applied automatically. When `json_prompt` is supplied, magic-prompt is skipped and the structured prompt is consumed directly; its `compositional_deconstruction.background` is replaced with a transparent-background directive. - `text_prompt` string — A natural-language prompt for image generation. When supplied, magic-prompt is enabled automatically. Mutually exclusive with `json_prompt`. - `json_prompt` V4JsonPrompt — Structured prompt for Ideogram 4.0 generation. When `json_prompt` is supplied, magic-prompt is disabled and the diffusion model consumes the JSON contract directly. Mutually exclusive with `text_prompt` and the legacy `prompt` field. - `high_level_description` string, required — One- or two-sentence overall description of the desired image. - `style_description` V4StyleDescription — Optional style description supplied alongside a V4 JSON prompt. - `aesthetics` string — Aesthetic notes (mood, vibe, references). - `art_style` string — Optional art-style hint (e.g., illustration, oil painting). - `lighting` string — Lighting description. - `medium` string — Medium description (e.g., photograph, digital art). - `photo` string — Optional photographic style notes (e.g., lens, film stock). - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock. - `compositional_deconstruction` V4CompositionalDeconstruction, required — The compositional breakdown of a V4 prompt — background plus an ordered list of elements. - `background` string, required — Description of the background of the scene. - `elements` V4PromptElement[], required — Ordered list of elements (objects and text) composing the scene. - union — A single element in the V4 prompt's compositional deconstruction. Discriminated by the `type` field. - object — A non-text element (object, character, background detail) in the V4 prompt layout. - `type` 'obj', required — Discriminator. Must be `obj`. - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution. - `desc` string, required — Description of the object element. - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock. - object — A text element to render in the V4 prompt layout. - `type` 'text', required — Discriminator. Must be `text`. - `bbox` integer[] — Bounding box for an element, expressed as four integers in `[0, 1000]` with `[y_min, x_min, y_max, x_max]` semantics (row-first). Values are normalized so the canvas is `1000 x 1000` regardless of the final resolution. - `text` string, required — The literal text to render in the image. - `desc` string, required — Description of the text element (style, role, placement notes). - `color_palette` string[] — Optional list of hex color strings (e.g. "#FFD700") that bias the Ideogram 4.0 output toward this palette. Applied as a soft color bias, not an exact per-pixel lock. - `tags` string[] — Round-trip metadata surfaced by the describe endpoint when `strip_tags=false`. Ignored by the v4 sampler on generate input. - `seed` integer, nullable — Random seed for reproducibility. - `magic_prompt_system_prompt_config_id` string — A base64url-encoded magic prompt system prompt config ID to use for this request. Honored when `text_prompt` is supplied. Ignored when `json_prompt` is supplied. - `aspect_ratio` 'AUTO' | '1x4' | '1x3' | '1x2' | '9x16' | '10x16' | '2x3' | '3x4' | '4x5' | '1x1' | '5x4' | '4x3' | '3x2' | '16x10' | '16x9' | '2x1' | '3x1' | '4x1' — The aspect ratio for an Ideogram 4.0 magic prompt. `AUTO` lets the model select the most suitable ratio from the prompt; any other value pins the ratio. The non-AUTO values are the buckets the 4.0 model supports. - `output_resolution` '1K' | '2K' | '4K' | '8K' — The output resolution tier for the generated image. Tiers are total-pixel budgets matching a square of the named size (for example, `8K` delivers at most 8192x8192 total pixels); wide and tall aspect ratios keep the same pixel budget, so a single dimension may exceed the named size. Defaults to 1K. - `rendering_speed` 'TURBO' | 'DEFAULT' | 'QUALITY' — The rendering speed to use. Defaults to DEFAULT. - `enable_copyright_detection` boolean, nullable — Optional. Opt this request into post-generation copyright detection (Hive likeness + logo checks). The effective gate is the OR of this field and the organization's `copyright_detection_enabled` setting on `/api`. See GenerateImageRequestV3 for details. ## Response `200` Image generated successfully. - ImageGenerationResponseV4 — The response which contains information about the generated image, including the download link. Images links are available for a limited period of time; if you would like to keep the image, you must download it. - `response_type` 'url' — Discriminator for the postGenerateDesignV4 oneOf response. Always "url" for this shape. - `created` string, date-time, required — The time the request was created. - `data` ImageGenerationObjectV4[], required — A list of ImageObjects that contain the generated image(s). - `url` string, uri, nullable — The direct link to the image generated. - `prompt` string, required — The prompt used for the generation. This may be different from the original prompt. - `resolution` string, required — The output resolution of the image, in the format WIDTHxHEIGHT (e.g. 1024x1024). Not limited to the request resolution presets, since some endpoints accept custom output sizes. - `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. ## Other responses - `400` — Invalid input provided. - `401` — Not authorized. - `422` — Prompt failed the safety check. - `429` — Too many requests. --- [API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/e7f5f98d7fdb/schema)