Ideogram

App · 25 actions

Generate, remix, edit, describe and upscale images with Ideogram, create and vectorize SVGs, and inspect generations, invoices and usage.

Actions

ActionWhat it does
Describe imageDescribe an image as a structured JSON prompt using Ideogram's 4.0 image captioner.
Generate autoGenerate images with the model Ideogram picks as best suited to each request, optionally editing images you upload.
Generate ideogram 2Generate images from a text prompt with Ideogram 2.0.
Generate ideogram 2aGenerate images from a text prompt with Ideogram 2a, a fast, lower-cost model.
Generate ideogram 3Generate images from a text prompt with Ideogram 3.0, with optional style codes, a style preset, a color palette and style reference images.
Generate ideogram 3 custom modelGenerate images with a custom Ideogram 3.0 model that you or your organization can access.
Generate ideogram 3 transparentGenerate images on a transparent background with Ideogram 3.0, as PNG files.
Generate ideogram 4Generate images with Ideogram 4.0 from a text or structured JSON prompt.
Generate ideogram 4 5Generate images with Ideogram 4.5 from a text or structured JSON prompt.
Generate ideogram 4 custom modelGenerate images with a custom Ideogram 4.0 model that you or your organization can access.
Generate ideogram 4 transparentGenerate images on a transparent background with Ideogram 4.0, as PNG files.
Generate svgGenerate SVG artwork from a prompt and optional reference images.
Get generationGet the status of a generation that runs in the background, and its images or video once it has finished.
Get usageGet your organization's billed usage over a time range, split into time buckets with the amount billed for each product.
Inpaint imageRepaint the masked area of an image with Ideogram 3.0, guided by a text prompt.
List invoicesGet your organization's invoices with their line items, with amounts in each invoice's currency.
Precise edit imageEdit an image with Ideogram 4.5 and get it back at its exact width and height.
Reframe imageExpand an image to a new size with Ideogram 3.0, keeping the original in the center and filling in the new area.
Remix imageTransform an image you upload with Ideogram 4.0, guided by a text prompt.
Remix image v3Transform an image you upload with Ideogram 3.0, guided by a text prompt.
Remove backgroundRemove the background from an image and return the subject as a transparent PNG.
Remove objectRemove the masked object from an image.
Replace backgroundReplace the background of an image from a text prompt with Ideogram 3.0, keeping the subject it detects; no mask is needed.
Upscale imageUpscale an image to 2, 4 or 8 times its size, with a model Ideogram picks for each request.
Vectorize imageConvert an image to SVG in the background.

Describe image

Describe an image as a structured JSON prompt using Ideogram's 4.0 image captioner. The result can be used as the prompt for the Ideogram 4 generate actions.

Inputs

ImageimagetextRequired
The image to describe (max 10MB). JPEG, PNG, and WebP are supported. Multipart requests only.
Include bboxinclude_bboxtrue/false
Whether to include bounding boxes for the subjects and text in the returned json_prompt. Defaults to true, so the prompt preserves the layout of the described image.Default: true.
Include style descriptionsinclude_style_descriptionstrue/false
Whether to include a free-form style description in the returned json_prompt. Defaults to false.Default: false.
Include tagsinclude_tagstrue/false
Whether to include free-form tags in the returned json_prompt. Defaults to false.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/describe/ideogram-4`. The `json_prompt` field is a structured `V4JsonPrompt` that can be passed back as `json_prompt` to the `/v1/ideogram-v4/generate` family of endpoints.
Example output
{
  "data": {
    "created": "example",
    "description_id": "example",
    "json_prompt": {
      "compositional_deconstruction": {
        "background": "example",
        "elements": []
      },
      "high_level_description": "example",
      "style_description": {
        "aesthetics": "example",
        "art_style": "example",
        "color_palette": [],
        "lighting": "example",
        "medium": "example",
        "photo": "example"
      }
    }
  }
}

Generate auto

Generate images with the model Ideogram picks as best suited to each request, optionally editing images you upload. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from or, when source images are supplied, the change to make to them.
Imagesimageslist
Optional source images to edit (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only.
Negative promptnegative_prompttext
Description of what to exclude from the images. The prompt takes precedence over the negative prompt. Not every model uses it. Cannot be combined with source images.
Aspect ratioaspect_ratiotext
The output aspect ratio. auto (the default) picks the most suitable ratio for the request. Without source images the value must be a supported ratio (for example "16x9" or "1x1"); with source images any "WIDTHxHEIGHT" value is accepted and the output uses the closest supported shape. Omit resolution when supplying a non-auto value.Default: auto.
Resolutionresolutiontext
The requested output resolution, formatted as "WIDTHxHEIGHT" (for example "1280x800"). The output is served at the closest resolution the selected model supports. Omit aspect_ratio (or leave it auto) when supplying a resolution.
Resolution tierresolution_tiertext
The output resolution tier. Affects which model serves the request, since not every model offers every tier. When omitted, the selected model's default tier is used.One of: 1k, 2k, 4k.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Privateprivatetrue/false
Whether the generated images should be kept private. When omitted, the default follows the caller's plan; some plans always generate privately.Default: true.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/auto`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 2

Generate images from a text prompt with Ideogram 2.0. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from.
Negative promptnegative_prompttext
Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Aspect ratioaspect_ratiotext
The aspect ratio for an Ideogram 3.x or 2.x generation. auto lets the model select a ratio from the prompt; any other value pins the ratio. Cannot be combined with resolution. Omitting the field is not auto: it uses 1x1.One of: auto, 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, and 6 more.
Rendering speedrendering_speedtext
The rendering speed to use. turbo generates faster at a lower cost, while quality prioritizes the highest-quality result.One of: turbo, default, quality. Default: default.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Style typestyle_typetext
The style type to generate with. When omitted, the model's default styling is used; pass auto to have a style selected automatically from the prompt.One of: auto, general, realistic, design, render_3d (Render 3d), anime.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-2`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 2a

Generate images from a text prompt with Ideogram 2a, a fast, lower-cost model. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Aspect ratioaspect_ratiotext
The aspect ratio for an Ideogram 3.x or 2.x generation. auto lets the model select a ratio from the prompt; any other value pins the ratio. Cannot be combined with resolution. Omitting the field is not auto: it uses 1x1.One of: auto, 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, and 6 more.
Rendering speedrendering_speedtext
The rendering speed to use. turbo generates faster at a lower cost, while quality prioritizes the highest-quality result.One of: turbo, default, quality. Default: default.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Style typestyle_typetext
The style type to generate with. When omitted, the model's default styling is used; pass auto to have a style selected automatically from the prompt.One of: auto, general, realistic, design, render_3d (Render 3d), anime.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-2a`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 3

Generate images from a text prompt with Ideogram 3.0, with optional style codes, a style preset, a color palette and style reference images. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from.
Negative promptnegative_prompttext
Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Resolutionresolutiontext
The resolutions supported for Ideogram 3.0.One of: 512x1536, 576x1408, 576x1472, 576x1536, 640x1344, 640x1408, 640x1472, 640x1536, 704x1152, 704x1216, and 59 more.
Aspect ratioaspect_ratiotext
The aspect ratio for an Ideogram 3.x or 2.x generation. auto lets the model select a ratio from the prompt; any other value pins the ratio. Cannot be combined with resolution. Omitting the field is not auto: it uses 1x1.One of: auto, 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, and 6 more.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Color palettecolor_paletteobject
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).
Style codesstyle_codeslist
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 typestyle_typetext
The style type to generate with.One of: auto, general, realistic, design, custom, fiction, stylized. Default: general.
Style presetstyle_presettext
A predefined style preset to apply to the generated images. Cannot be combined with style codes or style references.One of: 80s_illustration (80s illustration), 90s_nostalgia (90s nostalgia), abstract_organic (Abstract organic), analog_nostalgia (Analog nostalgia), art_brut (Art brut), art_deco (Art deco), art_poster (Art poster), aura, avant_garde (Avant garde), bauhaus, and 52 more.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-3`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 3 custom model

Generate images with a custom Ideogram 3.0 model that you or your organization can access. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from.
Custom model uricustom_model_uritextRequired
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 backgroundtransparent_backgroundtrue/false
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.Default: false.
Negative promptnegative_prompttext
Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Resolutionresolutiontext
The resolutions supported for Ideogram 3.0.One of: 512x1536, 576x1408, 576x1472, 576x1536, 640x1344, 640x1408, 640x1472, 640x1536, 704x1152, 704x1216, and 59 more.
Aspect ratioaspect_ratiotext
The aspect ratio for an Ideogram 3.x or 2.x generation. auto lets the model select a ratio from the prompt; any other value pins the ratio. Cannot be combined with resolution. Omitting the field is not auto: it uses 1x1.One of: auto, 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, and 6 more.
Rendering speedrendering_speedtext
The rendering speed to use. When omitted, a speed supported by the custom model is used.One of: turbo, default, quality.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Color palettecolor_paletteobject
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).
Style codesstyle_codeslist
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 presetstyle_presettext
A predefined style preset to apply to the generated images. Cannot be combined with style codes or style references.One of: 80s_illustration (80s illustration), 90s_nostalgia (90s nostalgia), abstract_organic (Abstract organic), analog_nostalgia (Analog nostalgia), art_brut (Art brut), art_deco (Art deco), art_poster (Art poster), aura, avant_garde (Avant garde), bauhaus, and 52 more.
Style reference imagesstyle_reference_imageslist
Images to use as style references (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-3-custom-model`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 3 transparent

Generate images on a transparent background with Ideogram 3.0, as PNG files. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from.
Negative promptnegative_prompttext
Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Upscale factorupscale_factortext
Optional enhancement factor applied after generation. x1 (the default) delivers the base render.One of: x1, x2, x4. Default: x1.
Aspect ratioaspect_ratiotext
The aspect ratio for an Ideogram 3.x or 2.x generation. auto lets the model select a ratio from the prompt; any other value pins the ratio. Cannot be combined with resolution. Omitting the field is not auto: it uses 1x1.One of: auto, 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, and 6 more.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-3-transparent`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 4

Generate images with Ideogram 4.0 from a text or structured JSON prompt. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from, in natural language or as a structured Ideogram 4.0 JSON prompt. A structured JSON prompt is used as is and skips magic prompt unless magic_prompt is on.
Magic promptmagic_prompttext
Controls how a natural-language prompt is prepared. auto (the default) and on rewrite and expand the prompt before generation. off keeps your wording and only converts it into a structured prompt. A valid structured JSON prompt skips magic prompt unless magic_prompt is on.One of: auto, on, off. Default: auto.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Resolutionresolutiontext
Optional. When supplied, the images are generated at this resolution. When omitted, an aspect ratio is picked automatically based on the prompt.One of: 2048x2048, 1440x2880, 2880x1440, 1664x2496, 2496x1664, 1792x2240, 2240x1792, 1440x2560, 2560x1440, 1600x2560, and 28 more.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-4`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 4 5

Generate images with Ideogram 4.5 from a text or structured JSON prompt. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from, or the edit instruction when source images are supplied. Natural language or a structured Ideogram 4.0 JSON prompt.
Magic promptmagic_prompttext
Controls how a natural-language prompt is prepared. auto (the default) and on rewrite and expand the prompt before generation. off keeps your wording and only converts it into a structured prompt. A valid structured JSON prompt skips magic prompt unless magic_prompt is on. With source images, every mode converts the edit instruction into a structured edit prompt.One of: auto, on, off. Default: auto.
Sizesizetext
The output size: "auto", "source" or an exact "WIDTHxHEIGHT". Without source images, an exact size must be one of the supported 1K/2K presets (for example 1024x1024, 2048x2048 or 1440x2880); "auto" or omitted picks a supported size based on the prompt. "source" is rejected. With source images, "auto" (the default) picks a supported 2K size based on the source images and the prompt, and "source" returns the output at the first source image's own width and height (scaled down, keeping its proportiDefault: auto.
Backgroundbackgroundtext
The output background. transparent returns images with an alpha channel, opaque returns a solid one, and auto decides for you.One of: auto, transparent, opaque. Default: auto.
Qualityqualitytext
The rendering quality to use. Higher quality takes longer and costs more. Defaults to medium with source images and high without. very_low, the fastest and cheapest, requires source images.One of: very_low (Very low), low, medium, high.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-4-5`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "generation_kind": "sampling",
    "seed": 1
  }
}

Generate ideogram 4 custom model

Generate images with a custom Ideogram 4.0 model that you or your organization can access. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from, in natural language or as a structured Ideogram 4.0 JSON prompt. A structured JSON prompt is used as is and skips magic prompt unless magic_prompt is on.
Custom model uricustom_model_uritextRequired
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.
Transparent backgroundtransparent_backgroundtrue/false
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.Default: false.
Magic promptmagic_prompttext
Controls how a natural-language prompt is prepared. auto (the default) and on rewrite and expand the prompt before generation. off keeps your wording and only converts it into a structured prompt. A valid structured JSON prompt skips magic prompt unless magic_prompt is on.One of: auto, on, off. Default: auto.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Resolutionresolutiontext
Optional. When supplied, the images are generated at this resolution. When omitted, an aspect ratio is picked automatically based on the prompt.One of: 2048x2048, 1440x2880, 2880x1440, 1664x2496, 2496x1664, 1792x2240, 2240x1792, 1440x2560, 2560x1440, 1600x2560, and 28 more.
Rendering speedrendering_speedtext
The rendering speed to use. When omitted, a speed supported by the custom model is used.One of: turbo, default, quality.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-4-custom-model`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate ideogram 4 transparent

Generate images on a transparent background with Ideogram 4.0, as PNG files. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt to generate images from, in natural language or as a structured Ideogram 4.0 JSON prompt. A structured JSON prompt is used as is and skips magic prompt, except that its background description is replaced with a transparent background.
Magic promptmagic_prompttext
Controls how a natural-language prompt is prepared. auto (the default) and on rewrite and expand the prompt before generation. off keeps your wording and only converts it into a structured prompt. A valid structured JSON prompt skips magic prompt unless magic_prompt is on.One of: auto, on, off. Default: auto.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Aspect ratioaspect_ratiotext
Supported output aspect ratios. The operation defines whether auto preserves the source shape or selects a shape from the prompt.One of: auto, 1x4, 1x3, 1x2, 9x16, 10x16, 2x3, 3x4, 4x5, 1x1, and 8 more. Default: auto.
Output resolutionoutput_resolutiontext
The output resolution tier. Each tier is a total pixel budget equal to a square of the named size (for example, 8k delivers at most 8192x8192 pixels in total). Wide and tall aspect ratios keep the same budget, so one side may exceed the named size. Tiers above 2k are produced by upscaling after generation. Defaults to 1k.One of: 1k, 2k, 4k, 8k. Default: 1k.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/generate/ideogram-4-transparent`. Synchronous requests (the default) include the generated images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed that was used, including when you did not set one.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Generate svg

Generate SVG artwork from a prompt and optional reference images.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
Prompt.
Image asset identifiersimage_asset_identifierslist
Existing uploaded or generated image references. Takes priority over images when both are supplied. The first image is the primary source; any others are additional references.
Imagesimageslist
Source images to transform, supplied as multipart file uploads. The first image is the primary source; any others are additional references.
Aspect ratioaspect_ratiotext
Supported output aspect ratios. The operation defines whether auto preserves the source shape or selects a shape from the prompt.One of: auto, 1x4, 1x3, 1x2, 9x16, 10x16, 2x3, 3x4, 4x5, 1x1, and 8 more. Default: auto.
Qualityqualitytext
Quality.One of: low, medium, high. Default: medium.
Num imagesnum_imagesnumber
Num images.From 1 to 8. Default: 1.
Seedseednumber
Seed.From 0 to 2147483647.
Privateprivatetrue/false
Outputs are private by default. Enterprise outputs are always private.Default: true.
Target collection idtarget_collection_idtext
URL-safe base64 ID of a writable destination collection.

Outputs

dataobject
Response.
Example output
{
  "data": {
    "generation_id": "example"
  }
}

Get generation

Get the status of a generation that runs in the background, and its images or video once it has finished. Failed generations include the reason.

Inputs

Generation idgeneration_idtextRequired
URL-safe base64 ID of the generation, as returned when the request was accepted.

Outputs

dataobject
The current status and, when complete, result data for an asynchronous generation.
Example output
{
  "data": {
    "created": "example",
    "data": [],
    "failure_reason": "example",
    "generation_id": "example",
    "response_type": "url",
    "status": "pending",
    "usage_cost_usd_micros": 1
  }
}

Get usage

Get your organization's billed usage over a time range, split into time buckets with the amount billed for each product. Usage may lag live traffic by a few minutes.

Inputs

Start timestart_timedate and timeRequired
Start of the reporting range (RFC 3339). Snapped down to the containing bucket boundary (UTC).
End timeend_timedate and time
End of the reporting range (RFC 3339), exclusive. Snapped up to the next bucket boundary (UTC). Defaults to now.
Bucket widthbucket_widthtext
Bucket granularity. 1d allows ranges up to 92 days per request; 1h allows up to 168 hours. Page through longer histories by moving start_time back across successive requests.One of: 1d, 1h. Default: 1d.
Sourcessourceslist
Which billing sources to include. api is usage from API requests; app is web-app usage, attributed to the member who generated it. Defaults to both, so report totals reconcile with invoices.One or more of: api, app. Default: ["api", "app"].

Outputs

dataobject
Response.
Example output
{
  "data": {
    "buckets": []
  }
}

Inpaint image

Repaint the masked area of an image with Ideogram 3.0, guided by a text prompt. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt describing the repainted result.
ImageimagetextRequired
The source image to repaint (max 25MB). JPEG, PNG, and WEBP are supported. Multipart requests only. The output matches its size, snapped to the nearest supported resolution.
MaskmasktextRequired
A black-and-white mask the same size as the source image. Black marks the region to repaint. JPEG, PNG, and WEBP are supported. Multipart requests only.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Style typestyle_typetext
The style type to generate with.One of: auto, general, realistic, design, custom, fiction, stylized. Default: general.
Style presetstyle_presettext
A predefined style preset to apply to the repainted images. Cannot be combined with style codes or style references.One of: 80s_illustration (80s illustration), 90s_nostalgia (90s nostalgia), abstract_organic (Abstract organic), analog_nostalgia (Analog nostalgia), art_brut (Art brut), art_deco (Art deco), art_poster (Art poster), aura, avant_garde (Avant garde), bauhaus, and 52 more.
Style codesstyle_codeslist
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 reference imagesstyle_reference_imageslist
Images to use as style references (max 10, max 25MB each). JPEG, PNG, and WEBP are supported.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
Asyncasync_valuetrue/false
When false (the default), the request waits until the repainted images are ready and returns them in data. When true, the request returns as soon as it is accepted; poll for completion and results with GET /v2/generations/{generation_id} using the returned generation_id.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/inpaint/ideogram-3`. Synchronous requests (the default) include the repainted images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v2/generations/{generation_id}` using the returned `generation_id`. The seed, width, and height report the values the request resolved to when the caller left them unset.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "height": 1,
    "seed": 1,
    "width": 1
  }
}

List invoices

Get your organization's invoices with their line items, with amounts in each invoice's currency. Needs an API key owned by an organization admin.

Inputs

None.

Outputs

dataobject
Response.
Example output
{
  "data": {
    "invoices": []
  }
}

Precise edit image

Edit an image with Ideogram 4.5 and get it back at its exact width and height. Editing the whole image is limited to about 4.2 million pixels (2048 by 2048), so larger images come back scaled down unless you set a context window to edit just one region at full size. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The edit instruction, in natural language or as a structured JSON prompt. Natural language is automatically converted into a structured prompt; valid structured JSON is used as is.
ImageimagetextRequired
The image to edit, as raw bytes (max 50MB and 67108864 pixels, which 8192x8192 meets exactly; JPEG, PNG, or WEBP). Multipart requests only, and ignored when the same image is also supplied by reference. The output always matches this image's width and height, and pixels the edit did not meaningfully change are copied exactly from it. Set context_window to keep the full resolution of an image over 4194304 pixels.
Reference imagesreference_imageslist
Optional images to guide the edit (max 4, max 50MB each; JPEG, PNG, or WEBP). They are never edited themselves; only image is. Multipart requests only, and ignored when the same references are also supplied by reference. A request with a mask can include at most three, because the mask takes up one reference slot.
Maskmasktext
An optional mask that limits the edit to part of image (max 50MB; JPEG, PNG, or WEBP). Multipart requests only. Black marks the area to edit and white the area to keep; values in between are rounded to the nearer of the two. The mask must have the same width and height as the image being edited and contain both black and white areas. A masked request can include at most three reference images.
Context windowcontext_windowtext
Which region of the image to edit. Set this to keep the full resolution of an image larger than 4194304 pixels. none, the default, edits the whole image, which is bounded by 4194304 pixels (the area of a 2048x2048 square); a larger image comes back scaled down to fit. For example, an 8192x8192 image returns as 2048x2048. auto requires a mask and fits a region around the masked area. If the mask selects more than 4194304 pixels no region fits it, and the request falls back to editing the whole imDefault: none.
Qualityqualitytext
The rendering quality to use. very_low is the fastest and cheapest, and high takes longer and is priced higher. This is the only field that affects the price: the size of the image you send does not change it, and neither does context_window.One of: very_low (Very low), low, medium, high. Default: medium.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
Asyncasync_valuetrue/false
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.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/precise-edit/ideogram-4-5`. Synchronous requests (the default) include the edited images in `data`. Asynchronous requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "generation_kind": "sampling",
    "seed": 1
  }
}

Reframe image

Expand an image to a new size with Ideogram 3.0, keeping the original in the center and filling in the new area. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
ImageimagetextRequired
The JPEG, PNG, or WEBP image to reframe (max 25MB). Multipart requests only.
ResolutionresolutiontextRequired
The resolutions supported for Ideogram 3.0.One of: 512x1536, 576x1408, 576x1472, 576x1536, 640x1344, 640x1408, 640x1472, 640x1536, 704x1152, 704x1216, and 59 more.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Rendering speedrendering_speedtext
Rendering speed.One of: turbo, default, quality. Default: default.
Style presetstyle_presettext
A predefined style preset that applies a specific artistic style to the generated image.One of: 80s_illustration (80s illustration), 90s_nostalgia (90s nostalgia), abstract_organic (Abstract organic), analog_nostalgia (Analog nostalgia), art_brut (Art brut), art_deco (Art deco), art_poster (Art poster), aura, avant_garde (Avant garde), bauhaus, and 52 more.
Color palettecolor_paletteobject
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).
Style codesstyle_codeslist
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 reference imagesstyle_reference_imageslist
JPEG, PNG, or WEBP style reference images (max 10, max 25MB each). Multipart requests only. Cannot be combined with style_preset or style_codes.
Asyncasync_valuetrue/false
Return immediately instead of waiting for reframed images.Default: false.

Outputs

dataobject
Synchronous requests (the default) include the reframed images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v2/generations/{generation_id}`. The seed reports the value the request resolved to when the caller left it unset.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Remix image

Transform an image you upload with Ideogram 4.0, guided by a text prompt. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt that guides the remix. It is always read as an editing instruction, so there is no magic_prompt option.
ImageimagetextRequired
The image to transform (max 50MB). JPEG, PNG, and WEBP are supported. Multipart requests only. The uploaded image is saved to your account as the remix's source. Omit resolution to keep its shape.
Image weightimage_weightnumber
Optional. How closely the result should follow the source image, from 1 to 100. When omitted the server chooses a value from your prompt, which is the usual case. Only accepted when the output keeps the source image's shape: combining image_weight with a resolution whose aspect ratio differs from the source's is rejected with a 400.From 1 to 100.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Resolutionresolutiontext
Optional. When supplied, the images are generated at this resolution. When omitted, the source image's shape is kept. A resolution whose aspect ratio differs from the source's cannot be combined with image_weight.One of: 2048x2048, 1440x2880, 2880x1440, 1664x2496, 2496x1664, 1792x2240, 2240x1792, 1440x2560, 2560x1440, 1600x2560, and 28 more.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
Asyncasync_valuetrue/false
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 for completion and results with GET /v2/generations/{generation_id} using the returned generation_id.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/remix/ideogram-4`. Synchronous requests (the default) include the remixed images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v2/generations/{generation_id}` using the returned `generation_id`. The seed reports the value the request resolved to.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Remix image v3

Transform an image you upload with Ideogram 3.0, guided by a text prompt. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
PromptprompttextRequired
The prompt that guides the remix.
ImageimagetextRequired
The image to transform (max 50MB). JPEG, PNG, and WEBP are supported. Multipart requests only. The uploaded image is saved to your account as the remix's source. Omit resolution and aspect_ratio to keep its shape; a different requested shape center-crops the source to fit first.
Image weightimage_weightnumber
Optional. How closely the result should follow the source image, from 1 to 100. When omitted the server chooses a value from your prompt, which is the usual case.From 1 to 100.
Negative promptnegative_prompttext
Description of what to exclude from the images. Descriptions in the prompt take precedence over descriptions in the negative prompt.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Resolutionresolutiontext
The resolutions supported for Ideogram 3.0.One of: 512x1536, 576x1408, 576x1472, 576x1536, 640x1344, 640x1408, 640x1472, 640x1536, 704x1152, 704x1216, and 59 more.
Aspect ratioaspect_ratiotext
Output aspect ratio. Cannot be combined with resolution. Generation defaults to 1x1; remix keeps the source ratio when both fields are omitted.One of: 1x3, 3x1, 1x2, 2x1, 9x16, 16x9, 10x16, 16x10, 2x3, 3x2, and 5 more.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Magic promptmagic_prompttext
Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of: auto, on, off. Default: auto.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Color palettecolor_paletteobject
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).
Style codesstyle_codeslist
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 typestyle_typetext
The style type to generate with.One of: auto, general, realistic, design, custom, fiction, stylized. Default: general.
Style presetstyle_presettext
A predefined style preset to apply to the remixed images. Cannot be combined with style codes or style references.One of: 80s_illustration (80s illustration), 90s_nostalgia (90s nostalgia), abstract_organic (Abstract organic), analog_nostalgia (Analog nostalgia), art_brut (Art brut), art_deco (Art deco), art_poster (Art poster), aura, avant_garde (Avant garde), bauhaus, and 52 more.
Style reference imagesstyle_reference_imageslist
Images to use as style references (max 10, max 25MB each). JPEG, PNG, and WEBP are supported.
Enable copyright detectionenable_copyright_detectiontrue/false
Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
Asyncasync_valuetrue/false
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 for completion and results with GET /v2/generations/{generation_id} using the returned generation_id.Default: false.

Outputs

dataobject
Response returned by `POST /v2/image/remix/ideogram-3`. Synchronous requests (the default) include the remixed images in `data`. Requests with `async` set to true omit `data`; poll for completion and results with `GET /v2/generations/{generation_id}` using the returned `generation_id`. The seed reports the value the request resolved to when the caller left it unset.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "seed": 1
  }
}

Remove background

Remove the background from an image and return the subject as a transparent PNG. Returns the result when it is ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
ImageimagetextRequired
The source image. JPEG, PNG, or WebP, up to 25MB. Multipart requests only.
Privateprivatetrue/false
Whether to keep the result out of the public gallery. When omitted, defaults to your plan's setting, or public if your plan has none. Enterprise generations are always private.Default: true.
Asyncasync_valuetrue/false
When false (the default), wait for and return the foreground image. When true, return as soon as the request is accepted; poll GET /v2/generations/{generation_id} for the result.Default: false.

Outputs

dataobject
Synchronous requests include exactly one foreground image in `data`. Async requests omit `data`; poll with `generation_id` for the result. If a synchronous request fails after the response has started streaming, the body contains `error` and `status_code` instead of `generation_id`.
Example output
{
  "data": {
    "data": [],
    "error": "example",
    "generation_id": "example",
    "status_code": 1
  }
}

Remove object

Remove the masked object from an image. Returns a generation ID; fetch the result with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
ImageimagetextRequired
The source image to remove an object from. JPEG, PNG, or WEBP, up to 50MB. Multipart requests only.
MaskmasktextRequired
A black-and-white mask the same size as the image; white (>= 128) marks the region to remove. JPEG, PNG, or WEBP, up to 50MB. Multipart requests only.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.

Outputs

dataobject
Acknowledgement that the request was accepted. Poll `GET /v2/generations/{generation_id}` with the returned `generation_id` for the result.
Example output
{
  "data": {
    "generation_id": "example"
  }
}

Replace background

Replace the background of an image from a text prompt with Ideogram 3.0, keeping the subject it detects; no mask is needed. Returns a generation ID; fetch the result with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
ImageimagetextRequired
The source image. JPEG, PNG, WEBP, HEIF, AVIF, GIF, BMP, TIFF, and MPO are supported, up to 50 MB. Multipart requests only. The longer side must be at most 3 times the shorter side; wider aspect ratios are rejected with a 400.
PromptprompttextRequired
Plain-language description of the desired new background.
Rendering speedrendering_speedtext
The rendering speed to use.One of: turbo, default, quality. Default: default.
Num imagesnum_imagesnumber
The number of images to generate.From 1 to 8. Default: 1.
Privateprivatetrue/false
Whether to keep the result private. When omitted, defaults to your plan's setting. Enterprise generations are always private.Default: true.

Outputs

dataobject
Acknowledgement that the request was accepted.
Example output
{
  "data": {
    "generation_id": "example"
  }
}

Upscale image

Upscale an image to 2, 4 or 8 times its size, with a model Ideogram picks for each request. Returns the images when they are ready; turn on Async to get a generation ID instead and fetch the result later with Get generation.

Inputs

Dry rundry_runtrue/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.Default: false.
ImageimagetextRequired
The source image to upscale, in a common format such as JPEG, PNG, or WEBP, up to 50MB. Multipart requests only. The uploaded image is used for this request only and is not stored.
Upscale factorupscale_factortext
How much to enlarge the source image: 2x, 4x, or 8x its original width and height. Rejected when the output would exceed 8192px on either side.One of: x2, x4, x8. Default: x2.
Seedseednumber
Random seed. Set for reproducible generation.From 0 to 2147483647.
Asyncasync_valuetrue/false
When false (the default), the request blocks until the upscaled image is ready and returns it in data. When true, the request returns as soon as it is accepted; poll GET /v2/generations/{generation_id} for the result.Default: false.

Outputs

dataobject
Synchronous requests (the default) include the upscaled image in `data`. Async requests omit `data`; poll `GET /v2/generations/{generation_id}` with the returned `generation_id`. `seed` is the seed actually used, and `width` and `height` are the output dimensions.
Example output
{
  "data": {
    "data": [],
    "generation_id": "example",
    "height": 1,
    "seed": 1,
    "width": 1
  }
}

Vectorize image

Convert an image to SVG in the background.

Inputs

Dry rundry_runtrue/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.Default: false.
Imageimagetext
JPEG, PNG or WEBP source; at most 50 MB. Multipart only.
Image asset identifierimage_asset_identifierobject
An identifier for an ideogram asset.
Modemodetext
Simple uses fewer shapes; detailed preserves fine detail; auto chooses the level of detail that best suits the image.One of: simple, detailed, auto. Default: auto.
Privateprivatetrue/false
Outputs are private by default. Enterprise outputs are always private.Default: true.
Target collection idtarget_collection_idtext
URL-safe base64 ID of a writable destination collection.

Outputs

dataobject
Response.
Example output
{
  "data": {
    "generation_id": "example"
  }
}

On this page