Kuro

Edit an image

edit_image

Change one thing about an image already in the account, keeping everything else. This is the studio's refine: the picture itself is the input, so instruction says only what changes and the rest of the frame is carried by the source's own pixels. Use this — never a second generate_image with a reworded prompt — whenever someone asks for the same picture with something different about it. Re-prompting rolls the dice again and returns a different composition, different lighting, different everything; this returns the same picture with the change applied, and files it as the next version of the original. The source's model, aspect ratio and setting are inherited unless you override them, and a source made by a model that cannot read a reference image is moved onto one that can. Costs a normal image generation.

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": {
      "generation_id": "<generation_id>",
      "instruction": "<instruction>"
    },
    "name": "edit_image"
  }
}

Input Schema

Name	Required	Description
`model`	No
`setting`	No
`instruction`	Yes	Only what changes — "cowboy hats instead of caps", "warmer light". Do not restate the original prompt: the picture is the input, and describing it again competes with what the model can already see.
`aspect_ratio`	No
`generation_id`	Yes

Output Schema

Name	Required	Description	Default
`message`	Yes
`generation`	Yes	One image, clip, voice-over or piece of music.

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedNov 4, 2026

addedOutput schema / properties / generation / description

Added value: +"One image, clip, voice-over or piece of music."

addedOutput schema / properties / generation / properties / app_url / description
```
Added value: +"Opens it in the app."
```
addedOutput schema / properties / generation / properties / aspect_ratio / description
```
Added value: +"Null for audio."
```
addedOutput schema / properties / generation / properties / created_at / format
```
Added value: +"date-time"
```

addedOutput schema / properties / generation / properties / credits

Added value: +{
+  "description": "Credits charged. Zero when your own provider key or the free allowance paid.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

removedOutput schema / properties / generation / properties / credits_cost
```
Removed value: -{
-  "type": [
-    "number",
-    "null"
-  ]
-}
```
addedOutput schema / properties / generation / properties / error / description
```
Added value: +"Why it failed. Null otherwise."
```
removedOutput schema / properties / generation / properties / generation_id
```
Removed value: -{
-  "format": "uuid",
-  "type": "string"
-}
```

addedOutput schema / properties / generation / properties / id

Added value: +{
+  "format": "uuid",
+  "type": "string"
+}

removedOutput schema / properties / generation / properties / kind

Removed value: -{
-  "enum": [
-    "image",
-    "video",
-    "audio",
-    "tool"
-  ],
-  "type": "string"
-}

addedOutput schema / properties / generation / properties / model / description
```
Added value: +"The model id it was made with (`GET /v1/models`)."
```

addedOutput schema / properties / generation / properties / object

Added value: +{
+  "const": "generation",
+  "type": "string"
+}

addedOutput schema / properties / generation / properties / output_url / description

Added value: +"The finished file, once `ready`. A signed link that works for about an hour; read the generation again for a fresh one."

addedOutput schema / properties / generation / properties / paid_by / description

Added value: +"Who paid: \"credits\", \"house\" (the free allowance), \"server\" (a server that charges nothing), or the vendor of your own key (\"replicate\", \"fal\", …)."

addedOutput schema / properties / generation / properties / ready_in_seconds / description

Added value: +"Roughly how long an unfinished generation has left; 0 means past its usual time."

addedOutput schema / properties / generation / properties / recipe_id

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/properties/generation/properties/id"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The recipe it was made with, if any."
+}

addedOutput schema / properties / generation / properties / status / description
```
Added value: +"`ready` and `failed` are final."
```

addedOutput schema / properties / generation / properties / thumbnail_url

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/properties/generation/properties/output_url/anyOf/0"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "A small still of the result, for a grid. Null for audio and while it works."
+}

addedOutput schema / properties / generation / properties / type

Added value: +{
+  "description": "What was made. New values may be added; treat an unknown one as opaque.",
+  "enum": [
+    "image",
+    "clip",
+    "voiceover",
+    "music",
+    "tool"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / generation / required

Previous value: -[
-  "generation_id",
-  "kind",
-  "status",
-  "model",
-  "prompt",
-  "aspect_ratio",
-  "refined_from",
-  "caption_style",
-  "output_url",
-  "credits_cost",
-  "paid_by",
-  "error",
-  "vendor_phase",
-  "stalled",
-  "ready_in_seconds",
-  "created_at",
-  "app_url"
-]New value: +[
+  "object",
+  "id",
+  "type",
+  "status",
+  "model",
+  "prompt",
+  "aspect_ratio",
+  "output_url",
+  "thumbnail_url",
+  "credits",
+  "paid_by",
+  "error",
+  "ready_in_seconds",
+  "recipe_id",
+  "created_at",
+  "app_url",
+  "refined_from",
+  "caption_style",
+  "vendor_phase",
+  "stalled"
+]

Changed2 schema fields changedOct 26, 2026

addedOutput schema / properties / generation / properties / paid_by
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

changedOutput schema / properties / generation / required

Previous value: -[
-  "generation_id",
-  "kind",
-  "status",
-  "model",
-  "prompt",
-  "aspect_ratio",
-  "refined_from",
-  "caption_style",
-  "output_url",
-  "credits_cost",
-  "error",
-  "vendor_phase",
-  "stalled",
-  "ready_in_seconds",
-  "created_at",
-  "app_url"
-]New value: +[
+  "generation_id",
+  "kind",
+  "status",
+  "model",
+  "prompt",
+  "aspect_ratio",
+  "refined_from",
+  "caption_style",
+  "output_url",
+  "credits_cost",
+  "paid_by",
+  "error",
+  "vendor_phase",
+  "stalled",
+  "ready_in_seconds",
+  "created_at",
+  "app_url"
+]

Changed2 schema fields changedOct 21, 2026

addedOutput schema / properties / generation / properties / ready_in_seconds
```
Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}
```

changedOutput schema / properties / generation / required

Previous value: -[
-  "generation_id",
-  "kind",
-  "status",
-  "model",
-  "prompt",
-  "aspect_ratio",
-  "refined_from",
-  "caption_style",
-  "output_url",
-  "credits_cost",
-  "error",
-  "vendor_phase",
-  "stalled",
-  "created_at",
-  "app_url"
-]New value: +[
+  "generation_id",
+  "kind",
+  "status",
+  "model",
+  "prompt",
+  "aspect_ratio",
+  "refined_from",
+  "caption_style",
+  "output_url",
+  "credits_cost",
+  "error",
+  "vendor_phase",
+  "stalled",
+  "ready_in_seconds",
+  "created_at",
+  "app_url"
+]

Changed2 schema fields changedOct 16, 2026

changedInput schema / properties / aspect_ratio / enum

Previous value: -[
-  "1:1",
-  "1:4",
-  "1:8",
-  "2:3",
-  "3:2",
-  "3:4",
-  "4:1",
-  "4:3",
-  "4:5",
-  "5:4",
-  "8:1",
-  "9:16",
-  "16:9",
-  "21:9"
-]New value: +[
+  "1:1",
+  "1:2",
+  "1:4",
+  "1:8",
+  "2:1",
+  "2:3",
+  "3:2",
+  "3:4",
+  "4:1",
+  "4:3",
+  "4:5",
+  "5:4",
+  "8:1",
+  "9:16",
+  "16:9",
+  "21:9"
+]

changedInput schema / properties / model / enum

Previous value: -[
-  "seedream-5-lite",
-  "nano-banana-2.1",
-  "nano-banana-2",
-  "gpt-image-2.5-flare",
-  "gpt-image-2.5-sunburst",
-  "gpt-image-2",
-  "nano-banana-2-lite",
-  "seedream-5-pro",
-  "flux-2-flex",
-  "flux-2-pro",
-  "flux-2-max",
-  "grok-imagine-image",
-  "grok-imagine-image-quality"
-]New value: +[
+  "seedream-5-lite",
+  "nano-banana-2.1",
+  "nano-banana-2",
+  "gpt-image-2.5-flare",
+  "gpt-image-2.5-sunburst",
+  "gpt-image-2",
+  "nano-banana-2-lite",
+  "seedream-5-pro",
+  "flux-2-flex",
+  "flux-2-pro",
+  "flux-2-max",
+  "grok-imagine-image",
+  "grok-imagine-image-quality",
+  "krea-3",
+  "qwen-image-3-pro"
+]

First observedOct 15, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false) it discloses that the result is filed as the next version of the original, that model/aspect ratio/setting are inherited unless overridden, that an incapable source model is silently moved onto a reference-capable one, and that it costs a normal image generation. These are exactly the behavioral facts annotations cannot express. It stops short of saying whether the edit is reversible or how failures are reported, but the disclosure is well above the bar.

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?

Front-loaded with the core action, and every paragraph carries a distinct fact: what it does, why not to re-prompt, what is inherited, what it costs. Slight over-writing in the 'different composition, different lighting, different everything' flourish and the 'studio's refine' framing, which could be trimmed without loss.

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?

For a 5-parameter generative mutation tool with an output schema and no destructive or auth caveats, the description covers the decision, the inheritance semantics, the model-substitution edge case and the credit cost. Nothing an agent needs to call it correctly is missing.

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 coverage is only 20% (only `instruction` is documented), so the description has to compensate and largely does: it clarifies that `instruction` describes only the delta rather than restating the prompt, and that `model`, `aspect_ratio` and `setting` are optional overrides of inherited source values. It never explicitly states that `generation_id` is the source image's id from the account, which is the one required parameter still left to inference.

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 and resource plus its distinguishing scope: 'Change one thing about an image already in the account, keeping everything else.' It explicitly positions itself against the nearest sibling, generate_image, so an agent can tell the two apart without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use trigger ('whenever someone asks for the same picture with something different about it') and an explicit when-not-to with the named alternative ('never a second generate_image with a reworded prompt'). The rationale — re-prompting returns a different composition and lighting — makes the routing rule memorable.

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

All Kuro tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?