Sign in

v4

latestOpenAPI 3.0.22026-08-02109239415.7 KB
generate

Generate with Ideogram 3.0 (Transparent Background)

Generates images with transparent background synchronously based on a given prompt and optional parameters using the Ideogram 3.0 model. Images will be generated using maximum supported resolution at the specified aspect ratio to allow best results with upscaler. The selected resolution is written to the response, not the upscaled final resolution.

rendering_speed=FLASH is not supported for transparent-background generation; the request will return a 400. Use TURBO, DEFAULT, or QUALITY instead.

Images links are available for a limited period of time; if you would like to keep the image, you must download it.

post/v1/ideogram-v3/generate-transparent

Request body

promptstring required

The prompt to use to generate the image.

seedinteger

Random seed. Set for reproducible generation.

upscale_factor'X1' | 'X2' | 'X4'

Upscale the initially generated image by the given factor. Upscale factors other than X1 will incur additional cost.

aspect_ratio'1x3' | '3x1' | '1x2' | '2x1' | '9x16' | '16x9' | '10x16' | '16x10' | '2x3' | '3x2' | '3x4' | '4x3' | '4x5' | '5x4' | '1x1'

The aspect ratio to use for image generation, which determines the image's resolution. Cannot be used in conjunction with resolution. Defaults to 1x1.

rendering_speed'FLASH' | 'TURBO' | 'BALANCED' | 'DEFAULT' | 'QUALITY'

The rendering speed to use.

magic_prompt'AUTO' | 'ON' | 'OFF'

Determine if MagicPrompt should be used in generating the request or not.

magic_prompt_system_prompt_config_idstring

A base64url-encoded magic prompt system prompt config ID to use for this request.

negative_promptstring

Description of what to exclude from an image. Descriptions in the prompt take precedence to descriptions in the negative prompt.

num_imagesinteger

Number of images to generate.

custom_model_uristring

A custom model URI in the format model/<model_name>/version/<version_name>. When provided, the model version and style will be resolved from this URI, and style_type is not required. A model must be able to generate transparent background to be used for this endpoint.

enable_copyright_detectionboolean 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: if the org has it on, this is ignored; if the org has it off, setting this true enables detection for this request only. Adds detection latency. Flagged images come back with is_image_safe: false.

Example request

{
  "prompt": "A photo of a cat",
  "seed": 12345,
  "upscale_factor": "X2",
  "magic_prompt": "ON",
  "negative_prompt": "brush strokes, painting",
  "custom_model_uri": "model/my-custom-model/version/1"
}

Response

Image(s) generated successfully.

createdstring date-time required

The time the request was created.

Example response

{
  "data": [
    {
      "style_type": "GENERAL",
      "seed": 12345,
      "upscaled_resolution": "4096x4096",
      "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": "1280x800",
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
      "is_image_safe": true
    },
    {
      "style_type": "GENERAL",
      "seed": 12345,
      "upscaled_resolution": "4096x4096",
      "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": "1280x800",
      "url": "https://ideogram.ai/api/images/ephemeral/xtdZiqPwRxqY1Y7NExFmzB.png?exp=1743867804&sig=e13e12677633f646d8531a153d20e2d3698dca9ee7661ee5ba4f3b64e7ec3f89",
      "is_image_safe": true
    }
  ],
  "created": "2000-01-23T04:56:07+00:00"
}