generate_image_set
Generate a cohesive SET of custom images on one SOLID-COLOR background or a TRANSPARENT one, each one a separate isolated subject sharing one visual style (icons, logos, game assets, UI elements, sprite/asset packs; transparent for images that drop onto any backdrop). The style parameter says how everything is drawn; the subjects parameter says what to draw; the background parameter is a color or "transparent". The style can also come from reference images via the styleReferences parameter - alone, or best combined with the style text (text plus references holds a style tightest). Returns a zip download URL. Cost: 1 credit per call. When a solid color fits the user's use case, it is the faster choice. Run generation calls sequentially, never in parallel - only one generation runs at a time per API key.
For composed, full-bleed pictures (scenes, hero images, banners, posters, environments), use generate_illustration_set instead.
For several images of ONE character (the same mascot, creature, person, or product in different poses or moods), use generate_character_set instead.
Output formats: PNG (lossless), JPEG, or WebP; JPEG has no alpha channel, so a set delivered transparent is PNG or WebP. Images can be delivered at a fixed width and height, at one fixed axis with the other hugging each subject, or at their native resolution.
Size and quality considerations: Leaving width and height unset delivers images at their native resolution, unscaled under relative sizing except that a subject far larger than the rest is shrunk (fill sizing scales each subject to its frame), which produces the highest quality results and is recommended when images will be post-processed, composited, or resized downstream. On a solid background, native output dimensions vary between generations and track the subject count - roughly 650-950px per side for small sets, down to roughly 400-650 at the full 16; fewer subjects means larger native images. Fixing width and height (e.g. 512 and 512) guarantees consistent dimensions across all images and generations but applies resampling which may soften fine details; fixing one axis lets each image keep its subject's own proportion on the other.
IMPORTANT - style and subject description rules for best results: The style applies to every image in the set, so it is what keeps them visually consistent. Put HOW the images are drawn (technique, palette, surface treatment) in the style, and make each subject description only about WHAT that one subject is, not how it looks. A quick test for any phrase: is it WHAT the subject is, or HOW it is drawn? HOW belongs in the style, shared across the set.
Get the style and the subject descriptions right with the user before you call. When their request puts how an image is drawn, a background, or a scene into a subject description (or names the subjects to draw in the style rather than as separate entries in the subjects list), fix it as you compose the call: routine moves of shared technique into the style you can just make, but when a change drops or alters something they explicitly asked for, tell them what you are adjusting and why first. Each call costs a credit, so it is worth getting this right up front rather than spending one on a framed or scene-filled result.
The style describes the visual treatment of the images (e.g. 'watercolor', 'pixel art', 'stained glass'). It must NOT mention background color, image count, layout, or sizing.
Do not list the subjects to draw in the style (e.g. 'illustrations of a fox, an owl, and a deer'); the style is only the shared visual treatment, and the subjects belong in the subjects list, one per entry. A category or theme word is fine (e.g. 'insect illustration').
Do not put background color or background descriptions in the style or subject descriptions.
Avoid framing the style as a type of painted canvas ('oil painting', 'acrylic painting', 'gouache painting', 'pastel painting'). These tend to produce each image as a rectangular framed canvas with its own colored background, rather than an isolated subject. Prefer 'illustration' or a specific technique: 'watercolor illustration', 'pen-and-ink sketch', 'ink wash', 'relief-etching', 'pastel drawing', 'woodblock print'.
Avoid color-field or atmospheric phrasings in the style ('luminous backgrounds of violet, rose, and gold', 'set against jewel-tone fields', 'dreamlike rainbow atmosphere'). These instruct the image model to fill each image with colored atmosphere, producing framed compositions rather than isolated subjects. Describe only the linework, palette, and technique of the subjects themselves.
Do not describe an aged, weathered, cracked, or textured surface, ground, wall, panel, or paper that the whole artwork sits on ('on aged wood', 'cracked fresco wall', 'aged parchment surface'); name the art tradition(s) or style(s) instead ('fresco-style illustration'). Texture that belongs to a subject's own material is fine ('a weathered bronze shield', 'a cracked ceramic vase').
No captions, labels, or annotations. Text that is part of the depicted object is fine (e.g. 'STOP' on a stop sign, 'EXIT' on an exit sign).
No grid lines, borders, frames, or separators.
No overlapping or collage-style arrangements.
Do not connect the subjects to each other or give them shared physical elements: no wires, cords, chains, ropes, ribbons, vines, or threads running between subjects, no frame or banner they share, no phrasing like 'connected by' or 'strung together', and no single continuous line or tube forming multiple subjects. Each subject must be drawable in complete isolation; connections inside one subject (a chain on an amulet, laces on a boot) are fine.
No dramatic/long drop shadows (subtle shadows are fine).
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').
Maximum 16 images per generation. Do not put the image count in the style.
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).
The style must actually describe a visual style, and each subject must name a drawable subject; text that does not is rejected.
Style description max length: 500 characters. Subject description max length: 200 characters each.
Size: width and height are separate parameters, each 256 to 512 pixels when given. Both given is an exact box; one given fixes that axis and the other hugs each subject (so images in the set differ on it, and it may fall below 256); neither given delivers native resolution, which is also the path to larger images.
Sizing: relative (the default) keeps the sizes the model gave the subjects in relation to one another, one scale for the whole set; fill scales each subject on its own to fill its frame less the margin, the icon-set convention, giving up relative size and enlarging subjects smaller than the frame (the result says by how much). Both can be changed later with edit_set.
Icons: the subject count sets how large a batch's icons can later be exported with export_set, crisp at every density: about a 136px base size with 13 to 16 subjects, 160 with 10 to 12, 180 with 7 to 9, 192 with 5 or 6, 256 with 4 or fewer. Every generation result states its batch's own crisp base size.
If the style 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".
To add more subjects to a set, call extend_image_set with the id of any batch in it, as often as the set needs.
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxKB | No | A file size limit for each image, in KB (1 KB = 1024 bytes), 10 to 10240; webp only (rejected with png or jpg). An image that fits keeps the quality set above; one that does not has its quality and the precision of its transparent edges lowered together, 5 quality points at a time down to 70, until it fits (a set below 70 keeps its quality and lowers only its edges), so images in a set can land at different qualities and the faintest edges of a busy transparent image can soften. An image still over the limit at the last step is delivered anyway and named in the result. For platforms that cap each file's size. Omit for no limit. | |
| style | No | Visual style for all images, e.g. flat minimalist, hand-drawn sketch, 3D glossy, pixel art. Text that does not describe a visual style is rejected. Provide this, styleReferences, or both - together they hold a style most tightly (the text pins the style, the references show it applied). | |
| width | No | Delivered width in pixels. Give both width and height for an exact box (every image lands on it, one uniform scale, the shorter axis padded); give only one and the other axis hugs each subject at that scale plus the margin (so images in the set differ on it); give neither and images arrive at their native size (relative sizing scales nothing but a subject far larger than the rest, fill scales each subject to its frame) - the highest detail, though dimensions then vary between generations. The per-axis range is given in the tool description; a given axis outside it is rejected, and the hugging axis is whatever each subject needs. A fixed size guarantees consistent dimensions across images and generations but applies Lanczos resampling which may soften fine detail; if the user will post-process the images, recommend leaving both unset. | |
| format | No | Output format: png, jpg, or webp. Defaults to png. jpg has no alpha channel, so a set delivered transparent is png or webp. | |
| height | No | Delivered height in pixels; see width for how the two combine (both: an exact box; one: the other axis hugs each subject; neither: native size). | |
| sizing | No | How subjects are scaled. relative (the default) keeps the sizes the model gave them in relation to one another: one scale for the whole set, so a small subject stays small in its frame. fill scales each subject on its own to fill the frame less the margin, touching it on one axis, so every image reads at the same visual weight (icon-set convention); that gives up relative size and enlarges any subject smaller than the frame, which the result reports when it happens. | |
| quality | No | Image quality for jpg/webp (1-100). Defaults to 90. | |
| 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). | |
| background | No | The background every image sits on: a 6-char hex color #RRGGBB (e.g. #ffffff, #2c3e50), or "transparent" for images with no background that drop onto any backdrop. Default is #ffffff. Do not mention background in the style or subject descriptions. | |
| validation | No | How to handle the automatic style/subject check before generating. One of: suggest (the default) - if the style and 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. | |
| minimumMargin | No | Minimum margin in pixels around each subject. Defaults to 20. At most 15% of the smallest given axis when width or height is given, at most 80 when neither is; negative values are rejected. With relative sizing the actual margin varies by subject and never falls below this (only the set's largest subject sits exactly on it); with fill sizing every subject touches it on one axis. | |
| styleReferences | No | Up to 3 reference images that define the style, alone or alongside the style parameter (with both, the text pins the style and the references show it applied - the tightest hold). Each entry is a ref_ token from the create_reference tool: create an upload slot, send the image file with the curl command it returns, then pass the token here. Image data itself never goes in a tool call; ref_ tokens are the only accepted form. Uploads take PNG, JPEG, or WebP; size and dimension limits are given in the create_reference tool's description, and oversized images are rejected with a clear message - larger reference images do not improve results. The images are used as style guides only: their rendering technique carries over, their subjects do not appear in the output. Provide at least one of style and styleReferences. |
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. |