Edit Image
xbrush_image_editEdit an image from a URL with text instructions. Supports inpainting (mask-based edits) and outpainting (canvas extension); runs asynchronously, so poll the request_id for results.
Instructions
Edit an image with text instructions. For inpainting use an edit model; for outpainting (extending the canvas) use an outpaint model — there is no separate outpaint tool. Submits async — poll the returned request_id with xbrush_get_request.
Args: model (string, required): Inpaint: qwen-image-edit, nano-banana-edit, seedream-4.5-edit. Outpaint: flux-outpaint, qwen-outpaint. See xbrush_list_models(category='image'). prompt (string, required): Text instruction for the edit. image_url (string, required): URL of the primary source image (also the first reference). image_urls (string[], optional): Additional reference image URLs for multi-reference models (gpt-image-2-edit, nano-banana-edit). Model receives [image_url, ...image_urls]. n (int, optional): Number of results (1-8). Default: 1. mask_url (string, optional): Mask image URL (white=edit, black=preserve). mode (string, optional): Hint 'inpaint'/'outpaint'; the chosen model determines the actual operation. width (int, optional): Output width (256-4096). Megapixel/outpaint models use it directly (outpaint: target canvas width). Resolution-based edit models ignore it UNLESS aspect_ratio:"custom" (see aspect_ratio). height (int, optional): Output height (256-4096). Same rules as width (outpaint: target canvas height). resolution (string, optional): Resolution tier for resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit), e.g. "1K"/"2K"/"4K". aspect_ratio (string, optional): Aspect ratio for resolution-based edit models. gpt-image-2-edit: 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 (1K/2K); only 16:9/9:16/21:9/1.91:1 at 4K. Special value "custom": gpt-image-2-edit outputs the exact width×height you pass (both required; each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400). quality (string, optional): low/medium/high — gpt-image-2-edit only. seed (int, optional): Random seed.
Note: resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit) ignore width/height — passing them returns an error. Exception: aspect_ratio:"custom" with width+height yields an EXACT pixel size on gpt-image-2-edit. Note: to give multiple reference images (e.g. compose two subjects with gpt-image-2-edit), put the primary in image_url and the rest in image_urls.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Number of edited images (1-8). Default: 1. | |
| mode | No | Optional hint ('inpaint'/'outpaint'). The selected model ultimately determines the operation — pick an outpaint model to outpaint. | |
| seed | No | Random seed for reproducible results. | |
| model | Yes | Editing model. Inpaint/instruct-edit: qwen-image-edit, nano-banana-edit, seedream-5.0-pro-edit, flux.2-pro-edit. Outpaint: flux-outpaint, qwen-outpaint. Use xbrush_list_models(category='image'). | |
| width | No | Output width in pixels (256-4096) for megapixel-based models; for outpaint models, the target canvas width. Resolution-based edit models normally ignore it — but with aspect_ratio:"custom", gpt-image-2-edit outputs exactly width×height (both required). | |
| height | No | Output height in pixels (256-4096) for megapixel-based models; for outpaint models, the target canvas height. Resolution-based edit models ignore it unless aspect_ratio:"custom" (see width). | |
| prompt | Yes | Text instruction describing the desired edits. | |
| quality | No | Output quality tier. Applies to byResolutionAndQuality models (gpt-image-2-edit); higher = better and more expensive. Server default is high if omitted. | |
| mask_url | No | Mask image URL. White areas = edit, black areas = preserve. | |
| image_url | Yes | URL of the primary source image to edit (also the first reference). | |
| image_urls | No | Additional reference image URLs for models that compose from multiple references (e.g. gpt-image-2-edit, nano-banana-edit). Appended after image_url, so the model receives [image_url, ...image_urls]. Omit for single-reference edits. | |
| resolution | No | Output resolution tier for resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit). Examples: "1K", "2K", "4K". | |
| aspect_ratio | No | Aspect ratio for resolution-based edit models (e.g. "16:9"). gpt-image-2-edit supports 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 at 1K/2K — at 4K only 16:9, 9:16, 21:9, 1.91:1. Special value "custom" makes gpt-image-2-edit use width×height as the exact output size (both required, each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400). seedream-*-edit / nano-banana-*-edit accept their own sets; an unsupported value is rejected with the list of allowed ratios. |