ideogram-mcp

Replace an image's background

ideogram_replace_background

Replace an image's background while keeping its subject by describing the new background in a prompt. Supports Ideogram 3.0 or GPT Image 2 and saves results to the output directory.

Instructions

Replace the background of an image and keep its subject (Ideogram 3.0 or GPT Image 2); the prompt describes the new background. Results are saved to the output directory; ideogram_quote prices a call first (nothing is generated).

Input Schema

Name	Required	Description
`image`	No	Local image file to work on, or a public https URL of one
`model`	No	The model (default ideogram-3); each takes the fields of its variant below
`prompt`	No	What to create or change, in natural language
`wait_s`	No	Seconds to wait for the result (0-50, default 45). The job is accepted first; if it is still running when the wait ends, the result is its generation_id for ideogram_generation (never resubmitted, never billed twice).
`private`	No	Keep the result out of Ideogram's public feed; true unless you set false (enterprise accounts are always private)
`quality`	No	very_low, low, medium or high: higher costs more
`num_images`	No	How many images to make (each is billed)
`inline_images`	No	true: each saved image is also returned as image content (base64; one over 3.75 MB, or past 10 MB in total, by path only), for a client without file access
`rendering_speed`	No	turbo, default or quality: faster is cheaper
`image_asset_identifier`	No	An Ideogram asset (an upload or an earlier result) instead of a local image

Schema Changelog

Changes observed during successful MCP inspections.

Changed26 schema fields changedv2.5.0Oct 12, 2026

addedInput schema / additionalProperties
```
Added value: +{}
```

addedInput schema / definitions

Added value: +{
+  "__schema0": {
+    "properties": {
+      "asset_id": {
+        "type": "string"
+      },
+      "asset_type": {
+        "enum": [
+          "ASSET",
+          "CANVAS_ASSET",
+          "LAYERED_ASSET",
+          "RESPONSE",
+          "UPLOAD"
+        ],
+        "type": "string"
+      },
+      "collection_id": {
+        "maxLength": 22,
+        "minLength": 22,
+        "pattern": "^[A-Za-z0-9_-]{22}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "asset_id",
+      "asset_type"
+    ],
+    "type": "object"
+  },
+  "shared0": {
+    "default": 1,
+    "maximum": 8,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "shared1": {
+    "maxLength": 4000,
+    "minLength": 1,
+    "pattern": "\\S",
+    "type": "string"
+  }
+}

addedInput schema / oneOf

Added value: +[
+  {
+    "properties": {
+      "image": {
+        "type": "string"
+      },
+      "image_asset_identifier": {
+        "$ref": "#/definitions/__schema0"
+      },
+      "model": {
+        "const": "gpt-image-2",
+        "type": "string"
+      },
+      "num_images": {
+        "$ref": "#/definitions/shared0"
+      },
+      "private": {
+        "type": "boolean"
+      },
+      "prompt": {
+        "$ref": "#/definitions/shared1"
+      },
+      "quality": {
+        "enum": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "model",
+      "prompt"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "image": {
+        "type": "string"
+      },
+      "image_asset_identifier": {
+        "$ref": "#/definitions/__schema0"
+      },
+      "model": {
+        "const": "ideogram-3",
+        "type": "string"
+      },
+      "num_images": {
+        "$ref": "#/definitions/shared0"
+      },
+      "private": {
+        "type": "boolean"
+      },
+      "prompt": {
+        "$ref": "#/definitions/shared1"
+      },
+      "rendering_speed": {
+        "default": "default",
+        "enum": [
+          "turbo",
+          "default",
+          "quality"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "prompt"
+    ],
+    "type": "object"
+  }
+]

changedInput schema / properties / image / description

Previous value: -"Local file path of the source image"New value: +"Local image file to work on, or a public https URL of one"

removedInput schema / properties / image / minLength
```
Removed value: -1
```
removedInput schema / properties / image / type
```
Removed value: -"string"
```

addedInput schema / properties / image_asset_identifier

Added value: +{
+  "description": "An Ideogram asset (an upload or an earlier result) instead of a local image"
+}

addedInput schema / properties / inline_images

Added value: +{
+  "description": "true: each saved image is also returned as image content (base64; one over 3.75 MB, or past 10 MB in total, by path only), for a client without file access",
+  "type": "boolean"
+}

removedInput schema / properties / magic_prompt

Removed value: -{
-  "description": "Auto-enhance prompts (default: AUTO)",
-  "enum": [
-    "AUTO",
-    "ON",
-    "OFF"
-  ],
-  "type": "string"
-}

addedInput schema / properties / model

Added value: +{
+  "description": "The model (default ideogram-3); each takes the fields of its variant below",
+  "enum": [
+    "gpt-image-2",
+    "ideogram-3"
+  ],
+  "type": "string"
+}

changedInput schema / properties / num_images / description

Previous value: -"Number of variations (1-8, default: 1)"New value: +"How many images to make (each is billed)"

removedInput schema / properties / num_images / maximum
```
Removed value: -8
```
removedInput schema / properties / num_images / minimum
```
Removed value: -1
```
removedInput schema / properties / num_images / type
```
Removed value: -"integer"
```

addedInput schema / properties / private

Added value: +{
+  "description": "Keep the result out of Ideogram's public feed; true unless you set false (enterprise accounts are always private)"
+}

changedInput schema / properties / prompt / description

Previous value: -"Description of the new background"New value: +"What to create or change, in natural language"

removedInput schema / properties / prompt / maxLength
```
Removed value: -10000
```
removedInput schema / properties / prompt / minLength
```
Removed value: -1
```
removedInput schema / properties / prompt / type
```
Removed value: -"string"
```

addedInput schema / properties / quality

Added value: +{
+  "description": "very_low, low, medium or high: higher costs more"
+}

changedInput schema / properties / rendering_speed / description

Previous value: -"Speed/quality tradeoff (default: DEFAULT)"New value: +"turbo, default or quality: faster is cheaper"

removedInput schema / properties / rendering_speed / enum

Removed value: -[
-  "FLASH",
-  "TURBO",
-  "DEFAULT",
-  "QUALITY"
-]

removedInput schema / properties / rendering_speed / type
```
Removed value: -"string"
```

removedInput schema / properties / seed

Removed value: -{
-  "description": "Reproducibility seed",
-  "maximum": 2147483647,
-  "minimum": 0,
-  "type": "integer"
-}

addedInput schema / properties / wait_s

Added value: +{
+  "description": "Seconds to wait for the result (0-50, default 45). The job is accepted first; if it is still running when the wait ends, the result is its generation_id for ideogram_generation (never resubmitted, never billed twice).",
+  "maximum": 50,
+  "minimum": 0,
+  "type": "integer"
+}

removedInput schema / required

Removed value: -[
-  "image",
-  "prompt"
-]

First observedv1.0.3Sep 25, 2026

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose two useful traits: results are written to the output directory, and ideogram_quote performs pricing without generating (no cost/side effect). It omits billing implications of num_images, the async wait/generation_id behavior, and privacy defaults, all of which only appear in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. The core action and subject-preservation constraint lead, followed by where output lands and the free pricing precheck. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, annotation-free, output-schema-free tool, the description covers the essentials an agent needs: what it does, what the prompt means, where results go, and the quote precheck. Remaining gaps (billing, async polling) are already documented in the schema fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so a 3 is the baseline. The description goes beyond it by explaining what the prompt actually controls here — it describes the new background, not the whole image — which is non-obvious for a background-replacement tool and guides prompt authoring.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair (replace an image's background) and adds a scope qualifier — the subject is preserved — which implicitly separates it from remove_background/remove_object. It also names the two supported models. It does not explicitly name a sibling to route against, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (image editing where the subject stays and the background changes) and helpfully points at ideogram_quote as a free pricing step. But it never says when to pick this over remove_background, inpaint, precise_edit or edit, which are the genuinely confusable siblings in this list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Replace an image's background

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools