Generate image
generate_imageGenerate an image from a text prompt, or edit and combine existing images with masks, region limits, transparent backgrounds, or split layers into separate PNGs.
Instructions
Create an image from a text prompt, or edit or combine existing images when images is given. The result says whether the user can already see the image; follow it. Write a specific prompt: subject, setting, composition, style, lighting, and any exact text in quotes. For edits, say what changes and what must stay the same. Make one image unless the user asks for more: every image costs them money. When the user asks for several different images at once, make ONE call with prompts (one prompt per image), never several calls: they then appear together as one gallery. When the user asks to split or separate an image into layers, or to get its elements as separate transparent PNGs, call this with layers: true and that one image.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "generate_image"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| out | No | Where to save, as a file path or a folder ending in "/". Only when the server runs on the user's machine. Default: generated-images/ in the project. | |
| mask | No | Limits an edit to part of the first image: a PNG the same size as it, transparent where the change may happen. Usually the id from the card's Select area tool. | |
| size | No | Exact pixels as WIDTHxHEIGHT, for example 1536x1024. Use aspect or size, not both. | |
| count | No | Variants of this one prompt. Default 1. | |
| erase | No | With mask or edit_regions: remove whatever is in that area and fill it in to match its surroundings. The card's Erase tool asks for this. | |
| model | No | A model id from list_image_providers. Omit for the provider's default. | |
| aspect | No | Shape as W:H, for example 1:1, 16:9, 9:16, 4:5, 3:2. | |
| images | No | Images to edit or use as references. Omit to create from text alone. | |
| layers | No | Split exactly one input image (by `images` or `selection: true`) into a base plus separate transparent PNG layers, one per element (Seedream only; runs on the whole image, so no mask or edit_regions; `prompt` is optional and may say how to split it). Billed per image returned, usually about 5. | |
| prompt | No | What to make. For edits: what to change and what to keep. | |
| prompts | No | Several different images in one go, one prompt each, shown together as one gallery. Use this in place of `prompt` when the user asks for more than one distinct image (for example an apple, a pear and cherries). For takes on a single prompt use `count`. | |
| quality | No | Leave this out unless the user asks for more quality: the default is the fast one. medium for a finished image, high for the finest detail; both are slower. | |
| fidelity | No | For edits with openai gpt-image-1.5: high keeps faces, logos and fine detail of the inputs closer to the original. | |
| provider | No | Omit to use the user's default provider. | |
| selection | No | Edit the image the user has open in the image card, limited to the area they painted on it if any. Use it when a message says "this image" or "the selected area" without an id; leave out `images`, `mask` and `erase`. | |
| background | No | transparent needs provider openai with model gpt-image-1.5. | |
| edit_regions | No | Limits an edit to rectangles of the first image, without needing a mask file. Each is fractions of the image from its top-left corner, for example the top third is { "x": 0, "y": 0, "width": 1, "height": 0.33 }. Supported by provider openai. |