generate_illustration_set
Generate a SET of illustrations in one consistent style - scenes, environments, hero images, banners, posters, portraits - one composed illustration per scene, every illustration in the call at the same size. The style parameter says how they are drawn, styleReferences shows that style in up to 3 reference images, and the scenes parameter says what each illustration shows. Without style references, the first scene is drawn first and the rest are drawn to match it. Returns a zip download URL. Each call costs 1 credit. Run generation calls sequentially, never in parallel - only one generation runs at a time per API key.
For separate isolated subjects on a plain or transparent background (icons, sprites, asset packs), use generate_image_set instead; for one character in many variations, generate_character_set.
width and height must be one of the supported pixel pairs below; any other pair is rejected. These are the maximums offered - nothing larger is available. Each line is one shape: the first pair is that shape's largest size, the rest are exact proportional downscales of it. To add scenes later, at this size or another from the list, use extend_illustration_set; to deliver a batch again at another of its sizes, format or quality, use edit_set.
2752x1536, 1376x768, 688x384 2048x2048, 1024x1024, 512x512, 256x256 1024x4128, 512x2064, 256x1032 704x5856, 352x2928 3168x1344, 1584x672, 792x336 1696x2528, 848x1264, 424x632 2528x1696, 1264x848, 632x424 1792x2400, 896x1200, 448x600 4128x1024, 2064x512, 1032x256 2400x1792, 1200x896, 600x448 1856x2304, 928x1152, 464x576 2304x1856, 1152x928, 576x464 5856x704, 2928x352 1536x2752, 768x1376, 384x688
IMPORTANT - style and scene rules for best results:
The style is how every illustration is drawn (medium, technique, palette, lighting treatment); each scene is what one illustration shows (its subject, setting, moment and composition). Keep the shared look in the style, so the set stays consistent.
Scene craft, since each call costs a credit: name the light and the time of day (cold blue twilight, one warm lamp from the left); fix the camera (wide establishing shot, three-quarter portrait, viewed from the doorway); and ask for open space on a named side when text will be laid over the illustration later.
Illustrations carry no text unless a scene asks for it: write any words that belong in an illustration, such as the name on a shop sign, into its scene.
Scenes must describe distinct illustrations; a scene that describes nothing to draw, or repeats another, is rejected, as is a style that does not describe a visual style.
Maximum 6 scenes per call. Style max length: 500 characters. Scene max length: 2500 characters each.
Formats: png (default, lossless), jpg, webp. quality (1-100) applies to jpg and webp; default 90.
To add more scenes to a set, call extend_illustration_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 |
|---|---|---|---|
| style | No | How every illustration in the set is drawn: medium, technique, palette, and lighting treatment (e.g. painterly storybook watercolor with warm golden light). Text that does not describe a visual style is rejected. Provide this, styleReferences, or both - together they hold a style most tightly. | |
| width | Yes | Width in pixels, together with height: one of the supported pixel pairs listed in the tool description. Every scene is delivered at this size. | |
| format | No | Output format: png, jpg, or webp. Defaults to png. | |
| height | Yes | Height in pixels, together with width: one of the supported pixel pairs listed in the tool description. | |
| scenes | Yes | What each illustration shows, one entry per illustration: either a list of scene descriptions or objects with description and filename (e.g. [{"description": "a harbor market at dawn", "filename": "hero.webp"}]). A scene is prose and may name a setting, a moment, the light and the camera. Entries must describe distinct illustrations; without a filename, the file is named from the start of its scene. | |
| quality | No | Image quality for jpg/webp (1-100). Defaults to 90. | |
| 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). | |
| styleReferences | No | Up to 3 reference images that define the style, alone or alongside the style parameter. 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. Their rendering carries over; their subjects and composition do not. 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 illustrations: each one's file name inside the zip, its scene, and its pixel width and height. | |
| zipURL | No | Download URL for the zip of illustrations. 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. | |
| 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. | |
| rejectedScenes | No | Present only when the request was rejected because some scenes do not appear to describe distinct illustrations: the exact rejected entries. No generation ran and nothing was charged; revise or remove them and resubmit. |