kie-mcp

grok_image_edit

Instructions

Edit an image with Grok Imagine Image 2.0 (4 credits). TWO MODES: (1) Region mode — pass task_id (a prior Grok 2.0 generation) + mask_indexs from grok_segment_map (run it first, free, pick regions by NAME): only those regions change. (2) Whole-image mode (NEW Aug 2026) — pass image_urls (ANY uploaded/external image, e.g. from upload_file) + aspect_ratio + prompt: instruction-based edit of the full image, no segmentation. Returns a new full image; result task_ids chain back into segment/edit for iterative refinement. Downloads to kie/assets/raw/.

Input Schema

Name	Required	Description
`prompt`	Yes	Region mode: what the masked region(s) should become plus what to preserve. Whole-image mode: the edit instruction for the full image.
`task_id`	No	Region mode: source task ID — a Grok Image 2.0 generation (or a previous grok_image_edit result). Mutually exclusive with image_urls.
`filename`	No	Output filename. Auto-generated if omitted.
`image_urls`	No	Whole-image mode: 1-5 public URL(s) of the image(s) to edit — any image, not just Grok generations (upload local files with upload_file first). Mutually exclusive with task_id.
`mask_indexs`	No	Region mode only: region indices from grok_segment_map (e.g. [1] or [0, 2]). Field name matches kie's API spelling.
`max_credits`	No	Refuse to submit if the estimated cost exceeds this many credits (overrides KIE_MAX_CREDITS_PER_CALL). Estimates come from published rates; kie bills the actual amount.
`aspect_ratio`	No	Whole-image mode: required output aspect ratio (auto keeps the input's shape).
`download_dir`	No	Absolute directory to save the file(s) into (created if missing). Defaults to the server's kie/assets/raw/. Must be absolute — the MCP server's working directory is not the caller's.
`estimate_only`	No	Return the estimated credit cost WITHOUT submitting anything. Use before expensive runs (video, 4K, 1080p upgrades, layer splits).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv5.8.0Oct 15, 2026

addedInput schema / properties / estimate_only

Added value: +{
+  "description": "Return the estimated credit cost WITHOUT submitting anything. Use before expensive runs (video, 4K, 1080p upgrades, layer splits).",
+  "type": "boolean"
+}

addedInput schema / properties / max_credits

Added value: +{
+  "description": "Refuse to submit if the estimated cost exceeds this many credits (overrides KIE_MAX_CREDITS_PER_CALL). Estimates come from published rates; kie bills the actual amount.",
+  "type": "number"
+}

Changed6 schema fields changedv5.3.0Sep 30, 2026

addedInput schema / properties / aspect_ratio

Added value: +{
+  "description": "Whole-image mode: required output aspect ratio (auto keeps the input's shape).",
+  "enum": [
+    "auto",
+    "1:1",
+    "2:3",
+    "3:2",
+    "16:9",
+    "9:16"
+  ],
+  "type": "string"
+}

addedInput schema / properties / image_urls

Added value: +{
+  "description": "Whole-image mode: 1-5 public URL(s) of the image(s) to edit — any image, not just Grok generations (upload local files with upload_file first). Mutually exclusive with task_id.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 5,
+  "type": "array"
+}

changedInput schema / properties / mask_indexs / description

Previous value: -"Region indices to edit, from grok_segment_map (e.g. [1] or [0, 2]). Field name matches kie's API spelling."New value: +"Region mode only: region indices from grok_segment_map (e.g. [1] or [0, 2]). Field name matches kie's API spelling."

changedInput schema / properties / prompt / description

Previous value: -"What the masked region(s) should become, plus what to preserve (e.g. \"change the background to a sunset beach, keep the apple unchanged\")"New value: +"Region mode: what the masked region(s) should become plus what to preserve. Whole-image mode: the edit instruction for the full image."

changedInput schema / properties / task_id / description

Previous value: -"Source task ID — a Grok Image 2.0 generation (or a previous grok_image_edit result)"New value: +"Region mode: source task ID — a Grok Image 2.0 generation (or a previous grok_image_edit result). Mutually exclusive with image_urls."

changedInput schema / required

Previous value: -[
-  "task_id",
-  "prompt",
-  "mask_indexs"
-]New value: +[
+  "prompt"
+]

Addedv4.8.0Aug 20, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden and does so well: it discloses the 4-credit cost, that segmentation is free, that the result is a NEW full image (implying the source is not destroyed), that result task_ids can be chained for iterative refinement, and that output downloads to kie/assets/raw/. It does not cover auth requirements or failure modes, so not a 5.

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

Conciseness4/5

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

Dense but well front-loaded: the core action and cost come first, then the two modes in parallel structure, then the return/chaining note. The parentheticals ("run it first, free", "NEW Aug 2026") are informative rather than filler, though the sentence is long enough that some readers may skim.

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

Completeness5/5

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

No output schema exists, and the description compensates by explaining what comes back (a new full image, reusable task_ids for chaining) and where files land. Combined with mode routing and the cost/estimate hint, an agent has everything needed to invoke this correctly.

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 the baseline is 3, but the description adds real signal by grouping the 9 parameters into two mutually exclusive modes and explaining cross-parameter interaction (task_id vs image_urls, when aspect_ratio applies). This helps an agent pick a valid parameter combination rather than just read individual field docs.

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

Purpose5/5

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

States a specific verb (Edit) and resource (image) with the exact model (Grok Imagine Image 2.0), and separates the tool into two named modes with distinct inputs. An agent can distinguish this from siblings like generate_image or grok_segment_map without opening the schema.

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

Usage Guidelines4/5

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

Gives explicit routing: region mode requires task_id + mask_indexs obtained from grok_segment_map (which it says to run first, free), whole-image mode accepts any image_urls plus aspect_ratio. It names related tools (grok_segment_map, upload_file) and their role. It stops short of stating when NOT to use this tool versus e.g. generate_image, so not a full 5.

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

grok_image_edit

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools