Ideogram
App · 25 actions
Generate, remix, edit, describe and upscale images with Ideogram, create and vectorize SVGs, and inspect generations, invoices and usage.
Actions
| Action | What it does |
|---|---|
| Describe image | Describe an image as a structured JSON prompt using Ideogram's 4.0 image captioner. |
| Generate auto | Generate images with the model Ideogram picks as best suited to each request, optionally editing images you upload. |
| Generate ideogram 2 | Generate images from a text prompt with Ideogram 2.0. |
| Generate ideogram 2a | Generate images from a text prompt with Ideogram 2a, a fast, lower-cost model. |
| 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. |
| Generate ideogram 3 custom model | Generate images with a custom Ideogram 3.0 model that you or your organization can access. |
| Generate ideogram 3 transparent | Generate images on a transparent background with Ideogram 3.0, as PNG files. |
| Generate ideogram 4 | Generate images with Ideogram 4.0 from a text or structured JSON prompt. |
| Generate ideogram 4 5 | Generate images with Ideogram 4.5 from a text or structured JSON prompt. |
| Generate ideogram 4 custom model | Generate images with a custom Ideogram 4.0 model that you or your organization can access. |
| Generate ideogram 4 transparent | Generate images on a transparent background with Ideogram 4.0, as PNG files. |
| Generate svg | Generate SVG artwork from a prompt and optional reference images. |
| Get generation | Get the status of a generation that runs in the background, and its images or video once it has finished. |
| Get usage | Get your organization's billed usage over a time range, split into time buckets with the amount billed for each product. |
| Inpaint image | Repaint the masked area of an image with Ideogram 3.0, guided by a text prompt. |
| List invoices | Get your organization's invoices with their line items, with amounts in each invoice's currency. |
| Precise edit image | Edit an image with Ideogram 4.5 and get it back at its exact width and height. |
| 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. |
| Remix image | Transform an image you upload with Ideogram 4.0, guided by a text prompt. |
| Remix image v3 | Transform an image you upload with Ideogram 3.0, guided by a text prompt. |
| Remove background | Remove the background from an image and return the subject as a transparent PNG. |
| Remove object | Remove the masked object from an image. |
| 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. |
| Upscale image | Upscale an image to 2, 4 or 8 times its size, with a model Ideogram picks for each request. |
| Vectorize image | Convert 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
- Image
imagetextRequired - The image to describe (max 10MB). JPEG, PNG, and WebP are supported. Multipart requests only.
- Include bbox
include_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 descriptions
include_style_descriptionstrue/false - Whether to include a free-form style description in the returned json_prompt. Defaults to false.Default:
false. - Include tags
include_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from or, when source images are supplied, the change to make to them.
- Images
imageslist - Optional source images to edit (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only.
- Negative prompt
negative_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 ratio
aspect_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. - Resolution
resolutiontext - 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 tier
resolution_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 prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Private
privatetrue/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. - Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from.
- Negative prompt
negative_prompttext - Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Aspect ratio
aspect_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 speed
rendering_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 prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Style type
style_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 detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Aspect ratio
aspect_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 speed
rendering_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 prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Style type
style_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 detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from.
- Negative prompt
negative_prompttext - Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Resolution
resolutiontext - The resolutions supported for Ideogram 3.0.One of:
512x1536,576x1408,576x1472,576x1536,640x1344,640x1408,640x1472,640x1536,704x1152,704x1216, and 59 more. - Aspect ratio
aspect_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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Magic prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Color palette
color_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 codes
style_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 type
style_typetext - The style type to generate with.One of:
auto,general,realistic,design,custom,fiction,stylized. Default:general. - Style preset
style_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 detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from.
- Custom model uri
custom_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 background
transparent_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 prompt
negative_prompttext - Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Resolution
resolutiontext - The resolutions supported for Ideogram 3.0.One of:
512x1536,576x1408,576x1472,576x1536,640x1344,640x1408,640x1472,640x1536,704x1152,704x1216, and 59 more. - Aspect ratio
aspect_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 speed
rendering_speedtext - The rendering speed to use. When omitted, a speed supported by the custom model is used.One of:
turbo,default,quality. - Magic prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Color palette
color_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 codes
style_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 preset
style_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 images
style_reference_imageslist - Images to use as style references (max 10, max 25MB each; JPEG, PNG, or WEBP). Multipart requests only.
- Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt to generate images from.
- Negative prompt
negative_prompttext - Description of what to exclude from the images. The prompt takes precedence over the negative prompt.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Upscale factor
upscale_factortext - Optional enhancement factor applied after generation. x1 (the default) delivers the base render.One of:
x1,x2,x4. Default:x1. - Aspect ratio
aspect_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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Magic prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - 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 prompt
magic_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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Resolution
resolutiontext - 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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - 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 prompt
magic_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. - Size
sizetext - 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. - Background
backgroundtext - 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. - Quality
qualitytext - 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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - 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 uri
custom_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 background
transparent_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 prompt
magic_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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Resolution
resolutiontext - 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 speed
rendering_speedtext - The rendering speed to use. When omitted, a speed supported by the custom model is used.One of:
turbo,default,quality. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - 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 prompt
magic_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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Aspect ratio
aspect_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 resolution
output_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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - Prompt.
- Image asset identifiers
image_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.
- Images
imageslist - Source images to transform, supplied as multipart file uploads. The first image is the primary source; any others are additional references.
- Aspect ratio
aspect_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. - Quality
qualitytext - Quality.One of:
low,medium,high. Default:medium. - Num images
num_imagesnumber - Num images.From 1 to 8. Default:
1. - Seed
seednumber - Seed.From 0 to 2147483647.
- Private
privatetrue/false - Outputs are private by default. Enterprise outputs are always private.Default:
true. - Target collection id
target_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 id
generation_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 time
start_timedate and timeRequired - Start of the reporting range (RFC 3339). Snapped down to the containing bucket boundary (UTC).
- End time
end_timedate and time - End of the reporting range (RFC 3339), exclusive. Snapped up to the next bucket boundary (UTC). Defaults to now.
- Bucket width
bucket_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. - Sources
sourceslist - 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 run
dry_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. - Prompt
prompttextRequired - The prompt describing the repainted result.
- Image
imagetextRequired - 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.
- Mask
masktextRequired - 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 prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Rendering speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Style type
style_typetext - The style type to generate with.One of:
auto,general,realistic,design,custom,fiction,stylized. Default:general. - Style preset
style_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 codes
style_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 images
style_reference_imageslist - Images to use as style references (max 10, max 25MB each). JPEG, PNG, and WEBP are supported.
- Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - 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.
- Image
imagetextRequired - 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 images
reference_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.
- Mask
masktext - 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 window
context_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. - Quality
qualitytext - 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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with is_image_safe: false.
- Async
async_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 run
dry_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. - Image
imagetextRequired - The JPEG, PNG, or WEBP image to reframe (max 25MB). Multipart requests only.
- Resolution
resolutiontextRequired - The resolutions supported for Ideogram 3.0.One of:
512x1536,576x1408,576x1472,576x1536,640x1344,640x1408,640x1472,640x1536,704x1152,704x1216, and 59 more. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Rendering speed
rendering_speedtext - Rendering speed.One of:
turbo,default,quality. Default:default. - Style preset
style_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 palette
color_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 codes
style_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 images
style_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.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt that guides the remix. It is always read as an editing instruction, so there is no magic_prompt option.
- Image
imagetextRequired - 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 weight
image_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 images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Resolution
resolutiontext - 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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
- Async
async_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 run
dry_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. - Prompt
prompttextRequired - The prompt that guides the remix.
- Image
imagetextRequired - 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 weight
image_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 prompt
negative_prompttext - Description of what to exclude from the images. Descriptions in the prompt take precedence over descriptions in the negative prompt.
- Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Resolution
resolutiontext - The resolutions supported for Ideogram 3.0.One of:
512x1536,576x1408,576x1472,576x1536,640x1344,640x1408,640x1472,640x1536,704x1152,704x1216, and 59 more. - Aspect ratio
aspect_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 speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Magic prompt
magic_prompttext - Controls magic prompt (automatic prompt rewriting). Defaults to auto.One of:
auto,on,off. Default:auto. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Color palette
color_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 codes
style_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 type
style_typetext - The style type to generate with.One of:
auto,general,realistic,design,custom,fiction,stylized. Default:general. - Style preset
style_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 images
style_reference_imageslist - Images to use as style references (max 10, max 25MB each). JPEG, PNG, and WEBP are supported.
- Enable copyright detection
enable_copyright_detectiontrue/false - Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.
- Async
async_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 run
dry_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. - Image
imagetextRequired - The source image. JPEG, PNG, or WebP, up to 25MB. Multipart requests only.
- Private
privatetrue/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. - Async
async_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 run
dry_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. - Image
imagetextRequired - The source image to remove an object from. JPEG, PNG, or WEBP, up to 50MB. Multipart requests only.
- Mask
masktextRequired - 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.
- Seed
seednumber - 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 run
dry_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. - Image
imagetextRequired - 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.
- Prompt
prompttextRequired - Plain-language description of the desired new background.
- Rendering speed
rendering_speedtext - The rendering speed to use.One of:
turbo,default,quality. Default:default. - Num images
num_imagesnumber - The number of images to generate.From 1 to 8. Default:
1. - Private
privatetrue/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 run
dry_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. - Image
imagetextRequired - 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 factor
upscale_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. - Seed
seednumber - Random seed. Set for reproducible generation.From 0 to 2147483647.
- Async
async_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 run
dry_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. - Image
imagetext - JPEG, PNG or WEBP source; at most 50 MB. Multipart only.
- Image asset identifier
image_asset_identifierobject - An identifier for an ideogram asset.
- Mode
modetext - 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. - Private
privatetrue/false - Outputs are private by default. Enterprise outputs are always private.Default:
true. - Target collection id
target_collection_idtext - URL-safe base64 ID of a writable destination collection.
Outputs
dataobject- Response.
Example output
{
"data": {
"generation_id": "example"
}
}