extend_image_set
Add more subjects to a set made with generate_image_set. The new batch is generated exactly as the set was - the same style text and style references, with the background (a color or transparent), size, format, quality, margin, sizing and file size limit of the batch you name - so a set grows past the 16-subject limit of one call without drifting; only the subjects are new. A set made with style references is sent them again, and only them; a set made from text alone is sent up to 3 images from its first batch, so the new subjects are drawn like the rest of the set. The new batch joins the set: listings show the batches together, and the whole set's download window restarts. Each call costs what a generation of the set costs: 1 credit per call. Run generation calls sequentially, never in parallel - only one generation runs at a time per API key.
Subjects that do not describe distinct, drawable subjects are refused before anything is generated or charged. To change the style, the size, or anything else, start a new set instead; to change only how an existing set is delivered, use edit_set.
IMPORTANT - subject description rules:
Subject descriptions should describe WHAT to depict, not where to position it.
Each image is ONE isolated subject, not a scene. Describe the subject with its pose or action and anything it directly holds, rides, or interacts with, but not the surrounding setting, environment, landscape, or sky. For composed scenes (a figure set within an environment), use generate_illustration_set instead.
Do not use size words (large, tiny, small, etc.) on the overall image subject (e.g. 'a large elephant', 'a tiny mouse') - all images are produced at the same size. Size words on details within the image are fine (e.g. 'a plate with a small insignia').
Subjects must be distinct: entries that differ only in case, punctuation, or spacing count as the same subject and the call is rejected. Explicit filenames must be distinct too (a different extension alone is not distinct).
Maximum 16 subjects per call, or fewer when the batch you name is fixed at a width or height above 512, since the new batch takes that size: up to 9 at 600 or less, up to 4 at 700 or less, and 1 above that. To add more per call, lower that batch's size first with edit_set.
If the subject check returns a suggested cleanup, show the user the specific changes and get their confirmation, then resubmit the approved prompt with validation set to "skip" so it generates exactly as approved (resubmitting without "skip" re-runs the check and may return further suggestions). See the validation parameter for when to use "skip" and "auto-apply".
If a "Rate limit exceeded" error is returned, wait the suggested number of seconds before retrying. Do not retry immediately.
Showing the result: as soon as the call returns, show the user every delivered image before you put them to use, then keep working without waiting for a reply (unless the user asked to review first), so they can ask for a change before anything is built on them. Show each image exactly as delivered, as its own file: the files are the product, and their exact size, margin and background are what the user asked for. Never present a new image made from them, even to check them; it hides all three. Files on disk or a link in your context are not delivery. Where you can open files on the user's machine, open the extracted index.html with the host's file opener; it shows each image at its delivered size with its dimensions. Where you can attach files to your reply, attach each delivered file as it is (attaching is not inspecting). Otherwise give the online viewer link and the zip link. Show every image unless the user asked for only some, and say in one line what you left out; if you can show none, say the set was made but you could not show it, and give the viewer link.
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": "<generation>",
"subjects": "<subjects>"
},
"name": "extend_image_set"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| subjects | Yes | Either a list of subject names (e.g. ["home", "search"]) or objects with description and filename (e.g. [{"description": "compass rose", "filename": "overview.webp"}]). Each subject must name a drawable subject and be distinct: entries differing only in case, punctuation, or spacing are rejected as the same subject. A subject with no Latin letters or numbers (a name written entirely in another script) needs the object form with a filename, since delivered files are named in ASCII. Write each subject as plain text, with no list marker such as "1." or "-" in front, no square brackets, and no invisible characters. | |
| unpackTo | No | Path on the caller's local filesystem where the generated files should be saved. The server does NOT write here. After this call returns, you (the calling client) must download images.zip from the returned zip URL, extract it to this path yourself, then report the path to the user. Make the download your immediate next action when the result arrives, before any commentary; the download URL expires (the result states when). | |
| generation | Yes | The id of any batch in the set to extend: the random segment of its download URL (.../download/<id>/images.zip), also returned by list_recent_generations. The new batch is generated exactly as that set: the same tool, style text and style references, and the named batch's background, size, format, quality, margin, sizing and file size limit. | |
| validation | No | How to handle the automatic subject check before generating. One of: suggest (the default) - if the new subject descriptions need cleanup for a consistent set, the cleaned version is returned as a suggestion for you to review before any image is generated; skip - skip the cleanup suggestions and generate exactly as given (the non-drawable-content and repeated-subject rejection rules above still apply; no mode skips them), set this when resubmitting a prompt you already revised from a previous suggestion (so your approved wording is used as-is and not re-checked, which avoids further suggestions) or when you are confident the prompt is already clean; auto-apply - if cleanup is needed, apply it and generate in one step without returning a suggestion. Omit for the default. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | ||
| format | No | The delivered image format. | |
| images | No | The generated images: each one's file name inside the zip, its subject, and its pixel width and height. | |
| zipURL | No | Download URL for the zip of generated images. Time-limited; expiresAt states the deadline. | |
| unpackTo | No | The caller-supplied local extraction path, echoed back. | |
| expiresAt | No | When the download URL expires. | |
| remaining | No | Credits remaining after this call. | |
| background | No | The background color used, or transparent. | |
| manifestURL | No | ||
| rejectedStyle | No | Present only when the request was rejected because the style does not appear to describe a visual style: the submitted style text. No generation ran and nothing was charged; revise the style (or drop it and use styleReferences) and resubmit. | |
| suggestedStyle | No | Present only on a validation suggestion: the cleaned style text, for review. An empty string means the cleanup removed the style entirely (nothing in it was usable as a style) - replace it, or use styleReferences. Absent when the style was not checked (references only, or an extension). No generation ran and nothing was charged. | |
| rejectedSubjects | No | Present only when the request was rejected because some subjects do not appear to name distinct, drawable subjects: the exact rejected entries. No generation ran and nothing was charged; revise or remove these subjects and resubmit. | |
| suggestedSubjects | No | Present only on a validation suggestion: the cleaned subject list, one entry per image. Adopt these, or resubmit your own wording with validation set to skip. |