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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "edit_image",
    "arguments": {
      "generation_id": "00000000-0000-4000-8000-000000000000",
      "instruction": "<instruction>"
    }
  }
}

{
  "type": "object",
  "properties": {
    "generation_id": {
      "type": "string",
      "format": "uuid"
    },
    "instruction": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "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."
    },
    "model": {
      "type": "string",
      "enum": [
        "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"
      ]
    },
    "aspect_ratio": {
      "type": "string",
      "enum": [
        "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"
      ]
    },
    "setting": {
      "type": "string"
    }
  },
  "required": [
    "generation_id",
    "instruction"
  ],
  "additionalProperties": false
}