Composed scenes in one consistent style, up to 6 per call, each call's illustrations at one size: the illustrations for a website, a series of posters, the scenes of a story. For separate subjects on a plain or transparent background, use the image set tools; for one character in many variations, the character set tools.
generate_illustration_setUp to 6 illustrations in one call, one per scene, styled by text, reference images, or both. 1 credit per call.
stylestringat least oneHow every illustration in the set is drawn: medium, technique, palette, and lighting treatment (painterly storybook watercolor with warm golden light). Provide this, styleReferences, or both; together they hold a style most tightly.
At most 500 characters, with no square brackets. Text that does not describe a visual style is rejected. Keep what each illustration shows in its scene, so the style stays the one thing every illustration shares.
styleReferencesstring[]at least oneUp to 3 reference images that define the style by example, alone or alongside style. Each entry is a ref_ token from the create_reference tool, which has its own guide covering uploads, limits, and token reuse.
Their rendering carries over; their subjects and composition do not.
scenesstring[] or object[]requiredWhat each illustration shows, one entry per illustration. Each entry is a string description, OR an object with { description, filename } to control the output filename.
Limits. At most 6 per call, each up to 2500 characters, with no square brackets. Scenes must describe distinct illustrations: one that describes nothing to draw, or repeats another in other words, is rejected before anything is generated or charged.
Filenames. Without a filename, a file is named from the start of its scene, cut at a word, and scenes that start alike are numbered _2, _3. A filename is cleaned up the same way as an image set's subjects, its extension replaced by the format's; two that name the same file are refused.
Writing them. A scene is prose: its subject, setting, moment, light and camera. See the scenes section.
widthintegerrequiredWidth in pixels, together with height: one of the supported sizes listed below. Every scene in the call is delivered at this size.
heightintegerrequiredHeight in pixels, together with width: one of the supported sizes listed below. Any other pair is rejected.
width and height of one of its sizes; the ratio name is only a label, and any pair not listed is rejected. Largest first in each row, the rest are exact proportional downscales.generate_illustration_set tool description carries the same list.formatstringoptionalpng is always lossless. jpg and webp use the quality parameter.
qualityintegeroptionalCompression quality for jpg and webp, from 1 (smallest file) to 100 (best quality). Ignored for png.
unpackTostringoptionalLocal filesystem path your MCP client should extract the returned zip into.
Any path on your machine, such as ~/my-project/art; your client extracts the zip there, since the server never writes to your disk. If omitted, the client picks a destination.
Beside its text reply, a call returns these fields, each only when it applies:
zipURLstringDownload URL for the zip of the set. It works until expiresAt.
expiresAtstringWhen the download URL expires, 30 days after the call.
imagesobject[]One entry per illustration: filename inside the zip, description (the scene it was made from, as the call gave it), width and height in pixels, and the file's size in bytes.
formatstringThe delivered image format.
stylestringThe style text the set was generated with. Absent when the style came from references alone.
remainingintegerCredits left on your key after this call.
unpackTostringYour unpackTo, echoed back.
rejectedStyle, rejectedScenesstring, string[]Only when the content check refused the request: the style text that does not describe a visual style, or the scenes that do not describe distinct illustrations, exactly as sent. The refusal comes back as a result, not an error. Nothing was generated or charged; revise them and resubmit.
extend_illustration_setAdds up to 6 more scenes to a set, drawn exactly as the set was: only the scenes are new, and the size too when you give one. 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 scenes are drawn like the rest of the set. Each call costs what generate_illustration_set costs.
generationstringrequiredThe 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 format and quality, and its size unless you give width and height.
scenesstring[] or object[]requiredWhat each illustration shows, one entry per illustration. Each entry is a string description, OR an object with { description, filename } to control the output filename.
Limits. At most 6 per call, each up to 2500 characters, with no square brackets. Scenes must describe distinct illustrations: one that describes nothing to draw, or repeats another in other words, is rejected before anything is generated or charged.
Filenames. Without a filename, a file is named from the start of its scene, cut at a word, and scenes that start alike are numbered _2, _3. A filename is cleaned up the same way as an image set's subjects, its extension replaced by the format's; two that name the same file are refused.
Writing them. A scene is prose: its subject, setting, moment, light and camera. See the scenes section.
widthintegeroptionalWidth in pixels, together with height: any size generate_illustration_set offers, so one set can hold a wide hero and tall posters. Left out, the new scenes are drawn at the size the batch you name is delivered at now.
heightintegeroptionalHeight in pixels, together with width; see width.
unpackTostringoptionalLocal filesystem path your MCP client should extract the returned zip into.
Any path on your machine, such as ~/my-project/art; your client extracts the zip there, since the server never writes to your disk. If omitted, the client picks a destination.
The same fields as generate_illustration_set returns.
Illustration sets deliver like every other set: your AI client receives a download URL that works for 30 days, fetches the ZIP, and extracts it into the path you passed as unpackTo. The detailed call above produces:
~/my-project/art/
├── hero.webp
├── a_fishing_village_harbor_at_noon.webp
├── a_lantern-lit_pier_at_night.webp
├── references/ (your styleReferences, or images from the set's first batch when extending a set made from text)
│ └── reference-1.png
├── prompt.json (the request, for your records)
└── index.html (preview viewer for the set)The index.html is a small preview page showing every illustration with its scene, and the style references when you used them. A batch can be delivered again with edit_set, at another file type or quality, or at another of its own sizes: the size its scenes were drawn at, or an exact half, quarter and so on of it, down to 256 pixels on the shorter side.
For the illustrations in an app or site, export_set exports a batch's scenes whole at every density the web, iOS, Android and Flutter need, up to a base size of a quarter of the longest side they were drawn at, so every file stays crisp.
The style says how every illustration is drawn; each scene says what one illustration shows: its subject, setting and moment, the light and the time of day, and where the camera stands. Leave the medium and palette to the style, so the set stays consistent. Illustrations carry no text unless a scene asks for it, so write any words that belong in an illustration, such as the name on a shop sign, into its scene.
a lone lighthouse on a rocky headland at the last minute of dusk, its beam cutting through low sea mist, long wet reflections on the rocks, wide shot with a low horizonPick the exact minute of light: the last minute of dusk reads warmer and moodier than evening.
a single credit card standing on edge on a wide sweep of paper, a crisp shadow falling to the left, open space on the right for a headlineAsk for open space on a named side when you plan to lay text over the illustration later.
a wizard's study at night viewed from the doorway: shelves of glowing potion bottles, a cat asleep on a fat spellbook, steam rising from a copper kettleAnchor the camera with a phrase like viewed from the doorway so the illustration commits to one vantage point.
a vast colony greenhouse under a cracked glass dome at dawn, rows of crops under grow-lights, two small figures walking the central pathDrop a small human figure into a vast scene and it sets the scale of everything else.
Without styleReferences, the first scene is drawn first and the rest are drawn to match it. Put first the scene that shows the style best; with references, every scene follows them instead.
A banner wants a wide shape, a phone wallpaper a tall one, an avatar a square. Pick the shape that fits from the supported sizes; to add another shape to the same set, extend it at that size.
The 6-scene ceiling is per call, not per set. Grow a set with extend_illustration_set: the id of any batch in it and the next scenes, and the new batch is drawn exactly as the set was, restarting the whole set's download window. Expanding a set from your generations does the same.