REST API at https://api.ideogram.ai for image generation, editing, training, and analysis. Endpoints include /v1/ideogram-v3/generate, edit, inpaint, remix, reframe, replace-background, layerize-text, upscale, describe, remove-background, and dataset + custom-model training endpoints. OpenAPI 3.1 published at developer.ideogram.ai.
openapi: 3.1.0
info:
title: API Reference
version: 1.0.0
paths:
/v1/ideogram-v3/generate:
post:
operationId: post-generate-image-v-3
summary: Generate with Ideogram 3.0
description: >
Generates images synchronously based on a given prompt and optional parameters using the Ideogram 3.0 model.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image(s) generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt failed the safety check.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to generate an image with Ideogram 3.0.
content:
multipart/form-data:
schema:
type: object
properties:
prompt:
type: string
description: The prompt to use to generate the image.
seed:
type: integer
description: Random seed. Set for reproducible generation.
resolution:
$ref: '#/components/schemas/ResolutionV3'
aspect_ratio:
$ref: '#/components/schemas/AspectRatioV3'
rendering_speed:
$ref: '#/components/schemas/RenderingSpeed'
magic_prompt:
$ref: '#/components/schemas/MagicPromptOption'
negative_prompt:
type: string
description: |
Description of what to exclude from an image. Descriptions in the prompt take precedence
to descriptions in the negative prompt.
num_images:
type: integer
default: 1
description: Number of images to generate.
color_palette:
$ref: '#/components/schemas/ColorPaletteWithPresetNameOrMembers'
style_codes:
type: array
items:
$ref: '#/components/schemas/StyleCode'
description: >-
A list of 8 character hexadecimal codes representing the style of the image. Cannot be used in
conjunction with style_reference_images or style_type.
style_type:
$ref: '#/components/schemas/StyleTypeV3'
style_preset:
$ref: '#/components/schemas/StylePresetV3'
custom_model_uri:
type: string
description: >
A custom model URI in the format model/<model_name>/version/<version_name>.
When provided, the model version and style will be resolved from this URI, and style_type is not
required.
style_reference_images:
type: array
items:
type: string
format: binary
description: >-
A set of images to use as style references (maximum total size 10MB across all style references).
The images should be in JPEG, PNG or WebP format.
character_reference_images:
type: array
items:
type: string
format: binary
description: >-
Generations with character reference are subject to the character reference pricing. A set of images
to use as character references (maximum total size 10MB across all character references), currently
only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.
character_reference_images_mask:
type: array
items:
type: string
format: binary
description: >-
Optional masks for character reference images. When provided, must match the number of
character_reference_images. Each mask should be a grayscale image of the same dimensions as the
corresponding character reference image. The images should be in JPEG, PNG or WebP format.
required:
- prompt
/v1/ideogram-v3/generate-transparent:
post:
operationId: post-generate-image-v-3-transparent
summary: Generate with Ideogram 3.0 (Transparent Background)
description: >
Generates images with transparent background synchronously based on a given prompt and optional parameters using
the Ideogram 3.0 model. Images will be generated using maximum supported resolution at the specified aspect
ratio
to allow best results with upscaler. The selected resolution is written to the response, not the upscaled final
resolution.
`rendering_speed=FLASH` is not supported for transparent-background generation; the request will return a 400.
Use `TURBO`, `DEFAULT`, or `QUALITY` instead.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image(s) generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt failed the safety check.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to generate an image with transparent background using Ideogram 3.0, with optional upscaling.
content:
multipart/form-data:
schema:
type: object
properties:
prompt:
type: string
description: The prompt to use to generate the image.
seed:
type: integer
description: Random seed. Set for reproducible generation.
upscale_factor:
$ref: '#/components/schemas/UpscaleFactor'
aspect_ratio:
$ref: '#/components/schemas/AspectRatioV3'
rendering_speed:
$ref: >-
#/components/schemas/V1IdeogramV3GenerateTransparentPostRequestBodyContentMultipartFormDataSchemaRenderingSpeed
description: >-
The rendering speed to use. FLASH is not supported for transparent-background generation; requests
with rendering_speed=FLASH will return a 400.
magic_prompt:
$ref: '#/components/schemas/MagicPromptOption'
negative_prompt:
type: string
description: |
Description of what to exclude from an image. Descriptions in the prompt take precedence
to descriptions in the negative prompt.
num_images:
type: integer
default: 1
description: Number of images to generate.
required:
- prompt
/v1/ideogram-v3/inpaint:
post:
operationId: post-inpaint-image-v-3
summary: Inpaint with Ideogram 3.0
description: >
Inpaint a given image synchronously using the provided mask with Ideogram 3.0. The mask indicates which part of
the image
should be edited, while the prompt and chosen style can further guide the edit.
Supported image formats include JPEG, PNG, and WebP.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image edits generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt or Initial Image failed the safety checks.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to inpaint an image with Ideogram 3.0.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: The image being edited (max size 10MB); only JPEG, WebP and PNG formats are supported at this time.
mask:
type: string
format: binary
description: >-
A black and white image of the same size as the image being edited (max size 10MB). Black regions in
the mask should match up with the regions of the image that you would like to edit; only JPEG, WebP
and PNG formats are supported at this time.
prompt:
type: string
description: The prompt used to describe the edited result.
magic_prompt:
$ref: '#/components/schemas/MagicPromptOption'
num_images:
$ref: '#/components/schemas/NumImages'
seed:
$ref: '#/components/schemas/Seed'
rendering_speed:
$ref: '#/components/schemas/RenderingSpeed'
style_type:
$ref: '#/components/schemas/StyleTypeV3'
style_preset:
$ref: '#/components/schemas/StylePresetV3'
color_palette:
$ref: '#/components/schemas/ColorPaletteWithPresetNameOrMembers'
style_codes:
$ref: '#/components/schemas/StyleCodes'
style_reference_images:
type: array
items:
type: string
format: binary
description: >-
A set of images to use as style references (maximum total size 10MB across all style references).
The images should be in JPEG, PNG or WebP format.
character_reference_images:
type: array
items:
type: string
format: binary
description: >-
Generations with character reference are subject to the character reference pricing. A set of images
to use as character references (maximum total size 10MB across all character references), currently
only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.
character_reference_images_mask:
type: array
items:
type: string
format: binary
description: >-
Optional masks for character reference images. When provided, must match the number of
character_reference_images. Each mask should be a grayscale image of the same dimensions as the
corresponding character reference image. The images should be in JPEG, PNG or WebP format.
required:
- image
- mask
- prompt
/v1/ideogram-v3/remix:
post:
operationId: post-remix-image-v-3
summary: Remix with Ideogram 3.0
description: >
Remix provided images synchronously based on a given prompt and optional parameters with the Ideogram 3.0 model.
Input images are cropped to the chosen aspect ratio before being remixed.
Supported image formats include JPEG, PNG, and WebP.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image(s) generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'403':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt or provided image failed safety check.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to remix an image with Ideogram 3.0.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image to remix binary (max size 10MB); only JPEG, WebP and PNG formats are supported at this
time.
prompt:
type: string
description: The prompt to use to generate the image.
image_weight:
type: integer
default: 50
seed:
$ref: '#/components/schemas/Seed'
resolution:
$ref: '#/components/schemas/ResolutionV3'
aspect_ratio:
$ref: '#/components/schemas/AspectRatioV3'
rendering_speed:
$ref: '#/components/schemas/RenderingSpeed'
magic_prompt:
$ref: '#/components/schemas/MagicPromptOption'
negative_prompt:
type: string
description: |
Description of what to exclude from an image. Descriptions in the prompt take precedence
to descriptions in the negative prompt.
num_images:
type: integer
default: 1
description: Number of images to generate.
color_palette:
$ref: '#/components/schemas/ColorPaletteWithPresetNameOrMembers'
style_codes:
$ref: '#/components/schemas/StyleCodes'
style_type:
$ref: '#/components/schemas/StyleTypeV3'
style_preset:
$ref: '#/components/schemas/StylePresetV3'
style_reference_images:
type: array
items:
type: string
format: binary
description: >-
A set of images to use as style references (maximum total size 10MB across all style references).
The images should be in JPEG, PNG or WebP format.
character_reference_images:
type: array
items:
type: string
format: binary
description: >-
Generations with character reference are subject to the character reference pricing. A set of images
to use as character references (maximum total size 10MB across all character references), currently
only supports 1 character reference image. The images should be in JPEG, PNG or WebP format.
character_reference_images_mask:
type: array
items:
type: string
format: binary
description: >-
Optional masks for character reference images. When provided, must match the number of
character_reference_images. Each mask should be a grayscale image of the same dimensions as the
corresponding character reference image. The images should be in JPEG, PNG or WebP format.
required:
- image
- prompt
/v1/ideogram-v3/reframe:
post:
operationId: post-reframe-image-v-3
summary: Reframe with Ideogram 3.0
description: >
Reframe a square image to a chosen resolution with Ideogram 3.0. The supported image formats include JPEG, PNG,
and WebP.
Image links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image re-frames generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt or Image failed the safety checks.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to reframe an image in a new resolution.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image being reframed (max size 10MB); only JPEG, WebP and PNG formats are supported at this
time.
resolution:
$ref: '#/components/schemas/ResolutionV3'
num_images:
$ref: '#/components/schemas/NumImages'
seed:
$ref: '#/components/schemas/Seed'
rendering_speed:
$ref: '#/components/schemas/RenderingSpeed'
style_preset:
$ref: '#/components/schemas/StylePresetV3'
color_palette:
$ref: '#/components/schemas/ColorPaletteWithPresetNameOrMembers'
style_codes:
$ref: '#/components/schemas/StyleCodes'
style_reference_images:
type: array
items:
type: string
format: binary
description: >-
A set of images to use as style references (maximum total size 10MB across all style references).
The images should be in JPEG, PNG or WebP format.
required:
- image
- resolution
/v1/ideogram-v3/replace-background:
post:
operationId: post-replace-background-v-3
summary: Replace Background with Ideogram 3.0
description: >
Replace the background of a given image synchronously using a prompt with Ideogram 3.0. The foreground subject
will be identified and kept, while the background is replaced based on the prompt and chosen style.
Supported image formats include JPEG, PNG, and WebP.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Background replacement generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationResponseV3'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'422':
description: Prompt or Initial Image failed the safety checks.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to replace the background of an image with Ideogram 3.0.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image whose background is being replaced (max size 10MB); only JPEG, WebP and PNG formats are
supported at this time.
prompt:
type: string
description: The prompt describing the desired new background.
magic_prompt:
$ref: '#/components/schemas/MagicPromptOption'
num_images:
$ref: '#/components/schemas/NumImages'
seed:
$ref: '#/components/schemas/Seed'
rendering_speed:
$ref: '#/components/schemas/RenderingSpeed'
style_preset:
$ref: '#/components/schemas/StylePresetV3'
color_palette:
$ref: '#/components/schemas/ColorPaletteWithPresetNameOrMembers'
style_codes:
$ref: '#/components/schemas/StyleCodes'
style_reference_images:
type: array
items:
type: string
format: binary
description: >-
A set of images to use as style references (maximum total size 10MB across all style references).
The images should be in JPEG, PNG or WebP format.
required:
- image
- prompt
/v1/remove-background:
post:
operationId: post-remove-background
summary: Remove Background
description: |
Remove the background of a given image synchronously. The foreground subject
is identified and returned on a transparent background. Supported image formats include JPEG,
PNG, and WebP.
Image links are available for a limited period of time; if you would like to keep the image,
you must download it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Background removed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveBackgroundResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to remove background.
content:
application/json:
schema:
description: Any type
'422':
description: Initial image failed the safety checks.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateImageSafetyError'
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to remove the background of an image.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image whose background is being removed (max size 10MB); only JPEG, WebP and PNG formats are
supported at this time.
required:
- image
/v1/ideogram-v3/layerize-text:
post:
operationId: post-layerize-text-v-3
summary: Layerize Text
description: >
Analyzes an image to detect text regions, then returns each detected text block with its position, content, font
information, and styling.
The response includes a text-erased base image (background with all text removed) and a flat list of detected
text blocks.
Supported image formats include JPEG, PNG, and WebP (max size 10MB).
Image links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Text layers detected and extracted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/LayerizeTextResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized.
content:
application/json:
schema:
description: Any type
'429':
description: Too many requests.
content:
application/json:
schema:
description: Any type
requestBody:
description: A request to detect and extract text layers from an image.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: >-
The image to analyze for text detection. The image should be in JPEG, PNG, or WebP format (max size
10MB).
prompt:
type: string
description: >-
An optional text description of the image. If not provided, a description will be auto-generated
from the image.
seed:
$ref: '#/components/schemas/Seed'
required:
- image
/v1/edit:
post:
operationId: post-v-1-edit-image
summary: Edit images with a prompt
description: >
Edit one or more images using a text prompt. Provide images via file upload
or Ideogram image URLs, and describe the desired edit in your prompt.
Supported image formats include JPEG, PNG, and WebP.
Images links are available for a limited period of time; if you would like to keep the image, you must download
it.
tags:
- subpackage_generate
parameters:
- name: Api-Key
in: header
description: API key for access control. Use in the header with the name \"Api-Key\"
required: true
schema:
type: string
responses:
'200':
description: Image edits generated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/V1EditImagesResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Not authorized to generate an image.
content:
application/json:
schema:
description: Any type
'402':
description: Insufficient credits or quota.
content:
application/json:
schema:
description: Any type
'422':
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ideogram/refs/heads/main/openapi/ideogram-openapi.yml