Ideogram Tool API
The tool API from Ideogram — 4 operation(s) for tool.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ideogram:ideogram-tool-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Ideogram API v2 Tool API
version: 1.0.0
servers:
- url: https://api.ideogram.ai
description: https://api.ideogram.ai
tags:
- name: tool
paths:
/v2/image/replace-background/ideogram-3:
post:
operationId: tool_replaceBackgroundIdeogramV3
summary: Replace background with Ideogram 3.0
description: 'Replace the background of an image from a text prompt with Ideogram 3.0,
keeping the automatically detected foreground subject; no mask is
needed. Upload the source `image` using `multipart/form-data`.
Returns a `generation_id`; poll `GET /v2/generations/{generation_id}`
or supply a `webhook_url`.'
tags:
- tool
parameters:
- name: dry_run
in: query
description: '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.
'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Background replacement accepted for asynchronous processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceBackgroundResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Unauthorized.
content:
application/json:
schema:
description: Any type
'402':
description: Insufficient credits or quota.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'403':
description: Not authorized to replace backgrounds.
content:
application/json:
schema:
description: Any type
'404':
description: The source image was not found or is not readable.
content:
application/json:
schema:
description: Any type
'422':
description: The prompt did not pass safety checks.
content:
application/json:
schema:
description: Any type
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'503':
description: Background replacement is temporarily unavailable.
content:
application/json:
schema:
description: Any type
requestBody:
description: The source image and a prompt describing its new background.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: '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:
type: string
pattern: \S
minLength: 1
maxLength: 4000
description: Plain-language description of the desired new background.
rendering_speed:
$ref: '#/components/schemas/V2ImageReplaceBackgroundIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed'
default: default
description: The rendering speed to use.
num_images:
type: integer
minimum: 1
maximum: 8
default: 1
description: The number of images to generate.
private:
type: boolean
description: 'Whether to keep the result private. When omitted, defaults to your
plan''s setting. Enterprise generations are always private.
'
webhook_url:
type: string
format: uri
maxLength: 2048
description: 'HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a
JSON POST to this URL once all images for the request have finished
generating. The body mirrors the synchronous generate response:
`request_id`, `created`, and a `data` array
containing every generated image (`url`, `prompt`, `resolution`, `seed`,
`is_image_safe`). Each delivery is signed with Ed25519 and verifiable
against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS;
private and loopback hosts and the cloud metadata service are rejected.
'
required:
- image
- prompt
security:
- ApiKeyAuth: []
/v2/image/replace-background/gpt-image-2:
post:
operationId: tool_replaceBackground
summary: Replace background with GPT Image 2
description: 'Replace the background of an image from a text prompt while keeping the
automatically detected foreground subject; no mask is needed. Upload
the source `image` using `multipart/form-data`.
Returns a `generation_id`; poll `GET /v2/generations/{generation_id}`
or supply a `webhook_url`.'
tags:
- tool
parameters:
- name: dry_run
in: query
description: '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.
'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Background replacement accepted for asynchronous processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceBackgroundResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Unauthorized.
content:
application/json:
schema:
description: Any type
'402':
description: Insufficient credits or quota.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'403':
description: Not authorized to replace backgrounds.
content:
application/json:
schema:
description: Any type
'404':
description: The source image was not found or is not readable.
content:
application/json:
schema:
description: Any type
'422':
description: The prompt did not pass safety checks.
content:
application/json:
schema:
description: Any type
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'503':
description: Background replacement is temporarily unavailable.
content:
application/json:
schema:
description: Any type
requestBody:
description: The source image and a prompt describing its new background.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: 'The source image. JPEG, PNG, WEBP, HEIF, AVIF, GIF, BMP, TIFF, and
MPO are supported, up to 50 MB. Multipart requests only.
'
prompt:
type: string
pattern: \S
minLength: 1
maxLength: 4000
description: Plain-language description of the desired new background.
quality:
$ref: '#/components/schemas/ReplaceBackgroundQuality'
default: high
description: The generation quality level. Defaults to `high`.
num_images:
type: integer
minimum: 1
maximum: 8
default: 1
description: The number of images to generate.
private:
type: boolean
description: 'Whether to keep the result private. When omitted, defaults to your
plan''s setting. Enterprise generations are always private.
'
webhook_url:
type: string
format: uri
maxLength: 2048
description: 'HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a
JSON POST to this URL once all images for the request have finished
generating. The body mirrors the synchronous generate response:
`request_id`, `created`, and a `data` array
containing every generated image (`url`, `prompt`, `resolution`, `seed`,
`is_image_safe`). Each delivery is signed with Ed25519 and verifiable
against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS;
private and loopback hosts and the cloud metadata service are rejected.
'
required:
- image
- prompt
security:
- ApiKeyAuth: []
/v2/image/remove-background/ideogram-1:
post:
operationId: tool_removeBackground
summary: Remove background
description: 'Remove the background from an image and return the foreground as a
transparent PNG. Upload the source `image` using `multipart/form-data`.
Returns the result directly by default; set `async` to get a
`generation_id` and poll `GET /v2/generations/{generation_id}`.'
tags:
- tool
parameters:
- name: dry_run
in: query
description: '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.
'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: The foreground image (synchronous requests), or an acknowledgement to poll (`async` requests). If a synchronous request fails after the response has started streaming, the HTTP status is already 200; the body contains `error` and `status_code` instead.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveBackgroundV2Response'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Unauthorized.
content:
application/json:
schema:
description: Any type
'402':
description: Insufficient credits or quota.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'403':
description: Not authorized to remove backgrounds.
content:
application/json:
schema:
description: Any type
'404':
description: The source image was not found or is not readable.
content:
application/json:
schema:
description: Any type
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'500':
description: The background-removal request failed.
content:
application/json:
schema:
description: Any type
'503':
description: Background removal is temporarily unavailable.
content:
application/json:
schema:
description: Any type
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: The source image. JPEG, PNG, or WebP, up to 25MB. Multipart requests only.
private:
type: boolean
description: '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.
'
async:
type: boolean
default: false
description: 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.
required:
- image
security:
- ApiKeyAuth: []
/v2/image/replace-background/ideogram-4-5:
post:
operationId: tool_replaceBackgroundIdeogram45
summary: Replace background with Ideogram 4.5
description: 'Rebuild the background of an image as the setting shown in a
`background_reference` image, with Ideogram 4.5 at its highest
quality. The people in the source image are kept, people in the
reference are left out, and results keep the source image''s aspect
ratio. Returns a `generation_id`; poll
`GET /v2/generations/{generation_id}` or supply a `webhook_url`.'
tags:
- tool
parameters:
- name: dry_run
in: query
description: '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.
'
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Background replacement accepted for asynchronous processing.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplaceBackgroundResponse'
'400':
description: Invalid input provided.
content:
application/json:
schema:
description: Any type
'401':
description: Unauthorized.
content:
application/json:
schema:
description: Any type
'402':
description: Insufficient credits or quota.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'403':
description: Not authorized to replace backgrounds.
content:
application/json:
schema:
description: Any type
'404':
description: An image was not found or is not readable.
content:
application/json:
schema:
description: Any type
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationErrorResponse'
'503':
description: Background replacement is temporarily unavailable.
content:
application/json:
schema:
description: Any type
requestBody:
description: The source image and the background reference.
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
description: 'The source image. JPEG, PNG, WEBP, HEIF, AVIF, GIF, BMP, TIFF, and
MPO are supported, up to 50 MB. Its longer side may be at most the
model''s maximum aspect ratio times its shorter side; a more extreme
proportion is rejected with a 400 that states the allowed range.
Multipart requests only.
'
background_reference:
type: string
format: binary
description: 'A photo of the setting the new background should match. Its people
are not copied. It is held to the same aspect-ratio limit as
`image`. Multipart requests only.
'
num_images:
type: integer
minimum: 1
maximum: 4
default: 1
description: The number of images to generate.
private:
type: boolean
description: 'Whether to keep the result private. When omitted, the result is
private. Enterprise generations are always private.
'
webhook_url:
type: string
format: uri
maxLength: 2048
description: 'HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a
JSON POST to this URL once all images for the request have finished
generating. The body mirrors the synchronous generate response:
`request_id`, `created`, and a `data` array
containing every generated image (`url`, `prompt`, `resolution`, `seed`,
`is_image_safe`). Each delivery is signed with Ed25519 and verifiable
against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS;
private and loopback hosts and the cloud metadata service are rejected.
'
required:
- image
- background_reference
security:
- ApiKeyAuth: []
components:
schemas:
GenerationErrorResponse:
type: object
properties:
error:
type: string
description: A message describing why the generation request was rejected.
reject_reason:
$ref: '#/components/schemas/GenerationRejectReason'
max_inflight_requests:
type: integer
minimum: 1
description: 'How many generations the account may have in progress at once on
the queue this request resolved to. Present when `reject_reason`
is `inflight_limit`.
'
task_completion_speed:
$ref: '#/components/schemas/GenerationErrorResponseTaskCompletionSpeed'
description: 'The queue this request resolved to. Present when `reject_reason`
is `inflight_limit`.
'
required:
- error
- reject_reason
description: A generation request rejected by an account or usage limit.
title: GenerationErrorResponse
ReplaceBackgroundQuality:
type: string
enum:
- low
- medium
- high
description: 'The quality tier for the edit. Higher tiers may improve detail and
take longer to complete.
'
title: ReplaceBackgroundQuality
ReplaceBackgroundResponse:
type: object
properties:
generation_id:
type: string
description: The generation ID to poll with `GET /v2/generations/{generation_id}`.
required:
- generation_id
description: Acknowledgement that the request was accepted.
title: ReplaceBackgroundResponse
GenerationRejectReason:
type: string
enum:
- insufficient_funds
- subscription_required
- daily_limit
- priority_credit_required
- inflight_limit
- feature_limit
description: The account or usage limit that rejected a generation request.
title: GenerationRejectReason
BackgroundRemovedImageObject:
type: object
properties:
url:
type:
- string
- 'null'
format: uri
description: Direct link to the foreground PNG. Empty when the output fails safety checks.
is_image_safe:
type: boolean
description: Whether the foreground image passed safety checks.
required:
- is_image_safe
title: BackgroundRemovedImageObject
GenerationErrorResponseTaskCompletionSpeed:
type: string
enum:
- fast
- slow
description: 'The queue this request resolved to. Present when `reject_reason`
is `inflight_limit`.
'
title: GenerationErrorResponseTaskCompletionSpeed
RemoveBackgroundV2Response:
type: object
properties:
generation_id:
type: string
description: The generation ID to poll with `GET /v2/generations/{generation_id}`.
data:
type: array
items:
$ref: '#/components/schemas/BackgroundRemovedImageObject'
description: The single foreground image. Present only for synchronous requests.
error:
type: string
description: Error message for a failure after the response started streaming.
status_code:
type: integer
description: The HTTP status the failure would have returned before streaming began.
description: '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`.
'
title: RemoveBackgroundV2Response
V2ImageReplaceBackgroundIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed:
type: string
enum:
- turbo
- default
- quality
default: default
description: The rendering speed to use.
title: V2ImageReplaceBackgroundIdeogram3PostRequestBodyContentMultipartFormDataSchemaRenderingSpeed
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: API key for access control. Use in the header with the name \"Api-Key\"