Skip to main content
Glama

remove image background

remove_image_background
Destructive

Remove an image background using a catalog model that supports remove_background. The selected model determines transparency support. Use get_model_catalog to choose a supported model and its settings. Returns a tracked task and playable result when complete.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sourceMediaId": "<sourceMediaId>",
      "model": "<model>"
    },
    "name": "remove_image_background"
  }
}

Input Schema

NameRequiredDescriptionDefault
modelYesActive model ID supporting this operation. Use get_model_catalog.
promptNoEdit or enhancement instructions.
maxCostUsdNoMaximum charge for each output. Checked against authoritative pricing before generation.
resolutionNo
aspectRatioNo
endFrameUrlNo
mediaInputsNoNamed media slots from get_model_catalog, for example reference_image_uri or mask_url.
scaleFactorNoUpscaling multiplier when supported by the selected model.
sparkTaskIdNoOriginating Spark task for library history and recovery.
workspaceIdNo
modelVariantNoVariant value from get_model_catalog variantSelector.options, such as high for Flare quality. Uses the catalog default when omitted.
outputFormatNoOutput format when supported by the selected model.
generateAudioNoExplicitly enable or disable generated video audio, when supported.
modelSettingsNoModel-specific controls using keys and options from get_model_catalog inputConstraints.slots or variantSelector.
sourceMediaIdYesCompleted workspace source media. The original is preserved.
idempotencyKeyNoStable request key. Retries with the same key reuse the existing output and do not start another paid generation.
sourceImageUrlNoPublic HTTP(S) source image/start-frame URL. Use mediaId for workspace images.
sourceVideoUrlNoPublic HTTP(S) source-video URL.
endFrameMediaIdNoWorkspace image for the final frame, when supported by the selected model.
referenceImagesNoImages to guide generation. Use labels such as person or product and refer to them as @person or @product in the prompt. Each item accepts a workspace mediaId or a public HTTP(S) URL.
sourceImageMediaIdNoWorkspace image to use as the source image/start frame.
sourceVideoMediaIdNoWorkspace video to edit or transform, when supported by the selected model.

Output Schema

NameRequiredDescriptionDefault
dataNo
errorNo
successYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / data / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "aspectRatio": {
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "downloadUrl": {
      -        "anyOf": [
      -          {
      -            "format": "uri",
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "durationMs": {
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "error": {
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "imageUrl": {
      -        "anyOf": [
      -          {
      -            "format": "uri",
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "mediaId": {
      -        "type": "string"
      -      },
      -      "model": {
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "playableUrl": {
      -        "anyOf": [
      -          {
      -            "format": "uri",
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "posterUrl": {
      -        "anyOf": [
      -          {
      -            "format": "uri",
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "progress": {
      -        "anyOf": [
      -          {
      -            "maximum": 1,
      -            "minimum": 0,
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "progressLabel": {
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "prompt": {
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "status": {
      -        "enum": [
      -          "queued",
      -          "generating",
      -          "completed",
      -          "failed"
      -        ],
      -        "type": "string"
      -      },
      -      "type": {
      -        "enum": [
      -          "image",
      -          "video",
      -          "audio"
      -        ],
      -        "type": "string"
      -      },
      -      "viewUrl": {
      -        "format": "uri",
      -        "type": "string"
      -      },
      -      "workspaceId": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "workspaceId",
      -      "mediaId",
      -      "type",
      -      "status",
      -      "progress",
      -      "progressLabel",
      -      "playableUrl",
      -      "imageUrl",
      -      "posterUrl",
      -      "downloadUrl",
      -      "viewUrl",
      -      "durationMs",
      -      "model",
      -      "aspectRatio",
      -      "prompt",
      -      "error"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "activeIndex": {
      -        "minimum": 0,
      -        "type": "integer"
      -      },
      -      "items": {
      -        "items": {
      -          "$ref": "#/properties/data/anyOf/0"
      -        },
      -        "maxItems": 8,
      -        "minItems": 1,
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "items",
      -      "activeIndex"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "aspectRatio": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "downloadUrl": {
      +        "anyOf": [
      +          {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "durationMs": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "elapsedSeconds": {
      +        "anyOf": [
      +          {
      +            "minimum": 0,
      +            "type": "number"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "error": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "heartbeatAgeSeconds": {
      +        "anyOf": [
      +          {
      +            "minimum": 0,
      +            "type": "number"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "height": {
      +        "anyOf": [
      +          {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "imageUrl": {
      +        "anyOf": [
      +          {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "lastHeartbeatAt": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "mediaId": {
      +        "type": "string"
      +      },
      +      "model": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "playableUrl": {
      +        "anyOf": [
      +          {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "posterUrl": {
      +        "anyOf": [
      +          {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "progress": {
      +        "anyOf": [
      +          {
      +            "maximum": 1,
      +            "minimum": 0,
      +            "type": "number"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "progressLabel": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "prompt": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "requestedAspectRatio": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "status": {
      +        "enum": [
      +          "queued",
      +          "generating",
      +          "completed",
      +          "failed"
      +        ],
      +        "type": "string"
      +      },
      +      "type": {
      +        "enum": [
      +          "image",
      +          "video",
      +          "audio"
      +        ],
      +        "type": "string"
      +      },
      +      "viewUrl": {
      +        "format": "uri",
      +        "type": "string"
      +      },
      +      "width": {
      +        "anyOf": [
      +          {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "workspaceId": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "workspaceId",
      +      "mediaId",
      +      "type",
      +      "status",
      +      "progress",
      +      "progressLabel",
      +      "playableUrl",
      +      "imageUrl",
      +      "posterUrl",
      +      "downloadUrl",
      +      "viewUrl",
      +      "durationMs",
      +      "model",
      +      "aspectRatio",
      +      "prompt",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "activeIndex": {
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "items": {
      +        "items": {
      +          "$ref": "#/properties/data/anyOf/0"
      +        },
      +        "maxItems": 8,
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "items",
      +      "activeIndex"
      +    ],
      +    "type": "object"
      +  }
      +]
  2. Changed2 schema fields changed
    • changedInput schema / properties / modelSettings / description
      Previous value: -"Model-specific controls using keys and options from get_model_catalog inputConstraints.slots."New value: +"Model-specific controls using keys and options from get_model_catalog inputConstraints.slots or variantSelector."
    • addedInput schema / properties / modelVariant
      Added value: +{
      +  "description": "Variant value from get_model_catalog variantSelector.options, such as high for Flare quality. Uses the catalog default when omitted.",
      +  "minLength": 1,
      +  "type": "string"
      +}
  3. First observed

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the mutation/no-idempotency profile is covered structurally. The description adds genuinely new behavioral context that the operation is asynchronous ('Returns a tracked task and playable result when complete') and that model choice governs output transparency. It omits cost implications despite a maxCostUsd parameter and does not note that the original media is preserved (that fact lives only 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?

Three short sentences, each earning its place: capability first, the model-selection dependency second, the async result contract last. Nothing is repeated from annotations or schema, and the most decision-relevant information is front-loaded.

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

Completeness3/5

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

With 22 parameters, nested objects and only 2 required fields, this is a complex tool, and the description covers the critical model-dependency and the async task return, while an output schema handles return details. It leaves gaps around the destructive/cost dimension that matter for a paid, non-idempotent generation call, so it is adequate rather than complete.

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

Parameters3/5

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

Schema description coverage is 82%, so parameter documentation is largely carried by the schema itself, establishing the baseline of 3. The description adds only that model selection determines transparency support, which is a useful semantic tie-in but does not explain the 20+ parameters (media inputs, idempotencyKey, maxCostUsd, scaleFactor) beyond what the schema already says.

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?

The description states a specific verb and resource ('Remove an image background') and adds the key constraint that the operation is model-driven ('using a catalog model that supports remove_background'), which distinguishes it from the video-background siblings. It does not explicitly differentiate from adjacent image tools such as edit_image or extract_product_image, so the identification is clear but not fully sibling-aware.

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?

It gives one concrete prerequisite: call get_model_catalog first to pick a supported model and settings, which is actionable routing guidance for an agent. However, it offers no when-to-use versus when-not guidance relative to other image tools (e.g., when to prefer edit_image or extract_product_image over this), so usage is implied rather than delimited.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.