# Logospell

> Custom image generation for AI agents over MCP (Model Context Protocol). Endpoint: https://mcp.logospell.com/mcp (streamable HTTP, bearer API key). Get a free API key at https://logospell.com. Generated downloads stay fetchable for 30 days after creation; only a new batch made with an extend tool or from a generation's own images (create_reference's sourceGeneration) restarts that set's window, so download and save files as soon as each generation returns. Each tool result states its exact expiry.

Logospell generates custom images from natural language. Three generation tools, and three that grow a set:
- generate_image_set: a cohesive SET of separate subjects on one SOLID-COLOR background, or TRANSPARENT (background "transparent") so each image can drop onto any backdrop (icons, logos, game assets, UI elements, sprite or asset packs). 1 credit per call. When a solid color works, it is the faster choice.
- generate_character_set: a set of ONE character (a mascot, creature, person, or single product), one variation of it per image, on a solid-color or a transparent background (sticker and reaction packs, mascot poses). The character comes from text, characterReferences images, or both; the variations list says what the character is doing in each image. 1 credit per call.
- generate_illustration_set: a SET of composed illustrations in one style (scenes, environments, hero images, banners, posters, portraits), one illustration per scene, every illustration in a call at one size from a fixed list in that tool's description. 1 credit per call, up to 6 scenes.
- extend_image_set, extend_character_set and extend_illustration_set: add more subjects, variations or scenes to an existing set, generated exactly as the set was. Priced as the set's own tool.

Choosing the right tool: separate subjects, each isolated on its own background (icons, logos, sprites, asset packs), are an image set: one generate_image_set call makes the whole cohesive set, on a solid color or transparent. Keep it an image set even when the listed subjects are described with settings around them: reduce each to its own subject. One character in many variations is a character set. Full composed pictures, each a scene with its own setting (a hero image, banners, posters, illustrations for a site's pages), are an illustration set, even when only one is wanted: put every scene the user wants in one generate_illustration_set call, so they share one style and one call's price, rather than one call per illustration.

Style from reference images: generate_image_set and generate_illustration_set accept styleReferences - up to 3 reference images that define the style by example, alone or together with the style text (text plus references holds a style most tightly). generate_character_set takes reference images too, as characterReferences: images of the character itself, not a style. Reference images are supplied ONLY through the free create_reference tool: call it to get an upload URL and a ref_ token, upload the image file with one command (curl -T <file> '<uploadURL>'), then pass the token in the tool's reference parameter. When the reference is an image from one of your OWN recent generations, skip the upload: create_reference with sourceGeneration and sourceImage fills the slot server-side. Never place image data inside a tool call. Tokens are private to the API key and reusable across any number of calls, and a token lasts 7 days from its last use or re-upload (each use restarts the window) - so upload each reference once and keep reusing its token for the rest of the session. list_references (free) lists your live references with their tokens, so a lost token can be recovered instead of uploading the image again.

Sets larger than one call allows: generate the set, then call extend_image_set (extend_character_set for a character set, extend_illustration_set for an illustration set) with the id of any batch in it and the next subjects, variations or scenes, as often as the set needs. The set supplies everything else - its tool, text, references and delivery settings - so every batch is anchored to the set's own source and none drifts; an illustration set can also grow at another size from its list. For a different style, start a new set.

Make generation calls one at a time: a call is rejected while another generation is still running on the same API key. Wait for each result before starting the next, and never fire generation calls in parallel - a proxy or gateway in between may queue parallel calls instead of rejecting them, and queued calls can time out waiting with the work still billed when it completes. A single set call already delivers the whole batch of images at once, so batch work rarely needs more than one call in flight.

A generation call can run for a minute or more, and larger sets and transparent image sets run longer; the server reports progress while it works and allows up to 6 minutes for one call. Give a call that long before treating it as failed, and check list_recent_generations before retrying: a call that seemed to fail may have completed and been billed.

Each generation returns a download URL that stays fetchable for 30 days (the result states the exact expiry). A batch made with an extend tool, or with references sourced from an earlier generation (create_reference's sourceGeneration) made by the same tool on the same kind of background, a color or transparent, joins that set and restarts the window for the whole set; a sourced reference used by another tool, or by the same tool on the other kind of background, restarts its source set's window without joining it. Nothing else renews it, editing included, so fetch and extract each result immediately, as your very first action after each call returns (before writing any reply text), never after a batch of generations. If a generation's result message is lost (for example the connection drops mid-call), do NOT blindly re-generate: the work may have completed and been billed. Call list_recent_generations first - it returns your recent successful generations with their download URLs (the original expiry still applies). When you already know a generation's id, get_generations returns just that one. Do not open, read, or otherwise inspect the generated image files yourself unless the user has asked you to: opening the index.html viewer (below) lets the user judge the results themselves, and pulling the images into your context wastes time and tokens. If your environment blocks the download (a proxy or sandbox refusing it, such as a 403 or "blocked-by-allowlist"), try once and stop: do not retry through other networks, devices or tools. Give the user the download URL, which opens in any browser with no key, and tell them their app's sandbox settings must allow the link's domain before you can fetch it (logospell.com/connect shows where for Claude's apps). Each delivery's index.html viewer is also online beside its zip (each result gives the link): where you cannot open local files for the user, give them that link rather than attaching index.html on its own, which shows no images without the files beside it.

After a successful set call (any generate or extend tool), the result includes a zip download URL. Download the zip and extract it into the unpackTo directory if the user supplied one, otherwise into a short, descriptive subfolder based on the style. After extracting, tell the user the full path where the images were saved and show the download URL with its expiry time. The zip includes a prompt.json recording the call (the same record get_generations returns) and an index.html that displays all generated images with their filenames, dimensions, and descriptions. 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. The host's file opener is open on macOS, xdg-open on Linux and start on Windows; use it without asking for confirmation first, never a browser-automation tool, which can mishandle local file paths.

Editing a delivered set: edit_set (free) changes how an existing set is delivered - its width and height, margin, sizing, format and quality, and for a character set or a transparent image set its background - by cutting it again from its full-resolution source, and replaces the set's download in place (same URL). Use it instead of generating again whenever only the delivery settings should change; a different picture is a new generation. A character set or a transparent image set can be delivered on any background color this way, or transparent, from one generation. On an illustration set it changes one batch's size (one of its own: the size its scenes were drawn at, or an exact half, quarter and so on of it), format and quality, cut again from the model's originals.

Files for an app or site: export_set (free) exports an existing set at the base size the user names - every image at every density the web, iOS, Android and Flutter need, laid out as each expects, with a viewer and a ledger - from the set's full-resolution source. An image or character set exports as icons, following its current margins and sizing (edit_set changes those first); an illustration set exports its scenes whole. One batch and one size per call. The ledger says per tree whether a density enlarged images past their source pixels. Every generation and edit_set result states its batch's crispBaseSize: an image or character set's is set by how many subjects or variations it holds at generation (generate_image_set's rules give the usual numbers), and edits to its size, canvas, margin or sizing can move it; an illustration set exports only up to its own, so its export is always crisp.

Deleting: delete_generations (free) permanently removes one or more of your generations before their download window closes (each download URL stops working, and the images and the source kept for edits and exports are removed), and delete_references (free) permanently removes one or more reference images. Only the API key that created an item can delete it, a delete cannot be undone, and credits are not refunded. Call them only when the user asks for a deletion, never to tidy up on your own: a deleted generation can no longer be edited or exported. Without them, generations and references expire on their own as described above.

Logospell claims no ownership of generated images. If the user asks what they may do with them, the ownership, commercial-use, and acceptable-use terms are at https://logospell.com/terms.

## Tools

### 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.

### generate_character_set

Generate a SET of images of ONE character - the same mascot, creature, person, or single product in every image - one isolated variation of it per image, on one SOLID-COLOR background or a TRANSPARENT one (sticker and reaction packs, mascot poses, a product shown many ways; transparent for stickers that drop onto any chat or backdrop). The character parameter describes who or what it is; characterReferences shows it in up to 3 reference images, the most faithful way to keep one specific character; the variations parameter says what it is doing in each image; the background parameter is a color or "transparent". Returns a zip download URL. Cost: 1 credit per call. Run generation calls sequentially, never in parallel - only one generation runs at a time per API key.

For many DIFFERENT subjects sharing one style, use generate_image_set instead.

Output formats: PNG (lossless), JPEG, or WebP; JPEG has no alpha channel, so a set delivered transparent is PNG or WebP.

Size and quality considerations match generate_image_set: leaving width and height unset delivers native resolution (best quality, varies between generations; relative sizing scales nothing but a variation far larger than the rest, fill scales each variation to its frame); fixing them resamples to that box, and fixing one axis lets the other hug each variation.

IMPORTANT - character and variation description rules for best results:
The character and its references decide WHO appears in every image; each variation decides only what that one character is doing in its image.
- Describe each variation by what the character is doing in it: its action and pose, what it is feeling and how strongly, its expression, and anything it holds or wears. Specific feelings at specific intensities give the most expressive sets (a slow-burning silent glare and a mid-leap scream read very differently).
- Each image is ONE isolated character, not a scene: describe the character and what it directly holds or interacts with, never the surrounding setting, environment, landscape, or sky.
- Do not use size words (large, tiny, small, etc.) on the character as a whole - all images are produced at the same size. Size words on what it holds or wears are fine (e.g. 'holding a tiny umbrella').
- Do not put background color or background descriptions in the character or variation text.
- No captions, labels, or annotations. Text that is part of a depicted object is fine.
- Do not connect the images to each other; each must be drawable on its own.
- Maximum 16 images per generation.
- Character description max length: 500 characters. Variation 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 variation (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 variations in relation to one another, one scale for the whole set; fill scales each variation on its own to fill its frame less the margin, the icon-set convention, giving up relative size and enlarging variations smaller than the frame (the result says by how much). Both can be changed later with edit_set.
- If the character 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 variations to a set, call extend_character_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.

### 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.
- 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.

### extend_character_set

Add more variations to a set made with generate_character_set. The new batch is generated exactly as the set was - the same character text and character 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-variation limit of one call without drifting; only the variations are new. A set made with character 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 variations 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.

Variations that do not describe distinct, drawable variations are refused before anything is generated or charged. To change the character, the size, or anything else, start a new set instead; to change only how an existing set is delivered, use edit_set.

IMPORTANT - variation description rules:
- Describe each variation by what the character is doing in it: its action and pose, what it is feeling and how strongly, its expression, and anything it holds or wears. Specific feelings at specific intensities give the most expressive sets (a slow-burning silent glare and a mid-leap scream read very differently).
- Each image is ONE isolated character, not a scene: describe the character and what it directly holds or interacts with, never the surrounding setting, environment, landscape, or sky.
- Do not use size words (large, tiny, small, etc.) on the character as a whole - all images are produced at the same size. Size words on what it holds or wears are fine (e.g. 'holding a tiny umbrella').
- Maximum 16 variations per call.
- If the variation 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.

### 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.

### extend_illustration_set

Add more scenes to a set made with generate_illustration_set. The new batch is drawn exactly as the set was - the same style text and style references, with the format and quality of the batch you name, and its size unless width and height are given (any size generate_illustration_set lists, so one set can hold a wide hero and tall posters). 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. The new batch joins the set: listings show the batches together, and the whole set's download window restarts. Each call costs 1 credit. Run generation calls sequentially, never in parallel - only one generation runs at a time per API key.

Scenes that do not describe distinct illustrations are refused before anything is generated or charged. To change the style, start a new set instead; to change only how a batch is delivered, use edit_set.

- Maximum 6 scenes per call. Scene max length: 2500 characters each.
- 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.

### list_recent_generations

List your recent successful generations and return their download URLs again. Use this to recover a generation whose result message was lost (for example a dropped connection mid-call): generations are billed when they complete, and their downloads stay available until their original expiry even if the response never arrived; re-listing does not extend the expiry. Generations made on the logospell.com generate page appear here too. Returns an index, newest first and a page at a time (limit and offset; total says how many there are): each generation's id, tool, creation and expiry times, zip download URL, its style or character text, its image count, whether it can be edited, and its parents (the set it extends, or the generations its references were copied from). For a generation's full record (the original call as promptJSON, where its reference images came from, and its current delivery settings), for example to extend or reproduce a set, pass its id to get_generations. Costs no credits.

### get_generations

Get the full record of generations of yours by id: each one's download URL and expiry, promptJSON (the original call, so the generation can be extended or reproduced), its current delivery settings, where its reference images came from, and its parents (the set it extends, or the generations its references were copied from). The ids come from list_recent_generations or from a generation's download URL. Ids that are not found are reported without failing the call, which fails only when none was found. Up to 50 ids per call. Costs no credits.

### create_reference

Create an upload slot for a reference image. Returns an upload URL and a ref_ token: upload the image file with one shell command (curl -T <file> '<uploadURL>'), then pass the ref_ token to the reference-image parameter you are filling - every parameter that takes reference images names this tool in its description. This is the ONLY way to supply reference images, and those parameters accept ref_ tokens and nothing else. Image data never goes inside a tool call: a call is JSON, so an embedded image would have to be base64 text that you, the caller, must emit character by character - slow, error-prone, and enough to exhaust your context window. The upload moves the bytes out-of-band instead: a plain HTTP PUT of the raw file, so any HTTP client works; if your environment has no way to send one, install curl. And when the image you want is from one of your OWN recent Logospell generations, skip the upload entirely: pass sourceGeneration and sourceImage and the server copies it directly (to grow an existing set, use its extend tool instead: extend_image_set, extend_character_set or extend_illustration_set). Accepts PNG, JPEG, or WebP, each at most 500KB, each side between 64px and 768px - resize before uploading if needed; larger reference images do not improve results. A reference is private to your API key and can be used in any number of later calls; it expires 7 days after its last use or re-upload (each use restarts the window), so uploading a few references once can serve a whole session of work. To update a reference, upload a new file to the same upload URL: its image is replaced and its ref_ token stays the same. Costs no credits.

### list_references

List your live reference images, most recently used or uploaded first: each one's ref_ token, its upload URL, when it expires, whether its image is in place, and the generation image it was filled from, if any. Use it to recover a token you lost instead of uploading the image again. References are private to your API key, at most 10 are live at once, and each expires 7 days after its last use or re-upload. Costs no credits.

### check_credits

Check how many image generation credits remain on your account: one balance shared by your MCP calls and the logospell.com generate page. Call it before generating to confirm the balance covers the call (each generation tool states its cost), or afterwards to see what is left. When credits run out, buy_credits returns a checkout link for more. It only reads the balance, changes nothing, and costs no credits.

### buy_credits

Buy more credits for your API key. Returns a Stripe Checkout link for 1 to 10 credit packs, already tied to this key's account, so no sign-in is needed. Calling this charges nothing: open the link in a browser if you can, or give it to the user, and the user completes the payment there with a card or Stripe Link. The credits are added to this key within seconds of payment; call check_credits to confirm. The result gives the purchase's credits and price. Costs no credits.

### edit_set

Change how an existing image set, character set or illustration set is delivered, without generating again: its width and height (both, one, or neither, exactly as on the set tools), its canvas when no size is fixed (one canvas for the whole set, or each image wrapped around its own subject), its minimum margin, its sizing (relative or fill), its format and quality, a file size limit per image on webp (maxKB), and for a character set or a transparent image set its background (any color, or transparent). The set is delivered again from its full-resolution source and its download is replaced in place: the same download URL now serves the new delivery, and get_generations reports the new levers. Free; no credits are spent. What the pictures show (the style or character, the subjects, variations or scenes, and the references) cannot be edited - a different picture is a new set.

On an illustration set, width and height go together and must be one of the batch's own sizes: the size its scenes were drawn at (get_generations' nativeWidth and nativeHeight) or an exact half, quarter and so on of it, down to 256 pixels on the shorter side. Format and quality apply as on the other sets; canvas, margin, sizing, background and maxKB do not. At the native size in the model's own format, the originals themselves are delivered.

A lever left out keeps its current value, so one call can change one thing. Any earlier state, the original delivery included, is one edit away: nothing is kept as history because the same levers always produce the same bytes. Editing never extends a set's download window.

jpg has no alpha: asking for jpg on a set delivered transparent composes the images over white unless a background color is in force (given in the same call or kept from an earlier edit); jpg together with background "transparent" is rejected. background applies to character sets and transparent image sets only. Not available for sets generated before editing existed (they have no source).

The user asked for this change to see it: as soon as the call returns, fetch the replaced zip and show them every image exactly as delivered, each as its own file (open the extracted index.html, attach each file as it is, or give the viewer link). Never present a new image made from them.

### export_set

Export an existing set for the web, iOS, Android and Flutter, free: every image at the base size you name and at every density each platform needs, laid out as each expects (web files with @2x and @3x and an srcset line, an iOS asset catalog with one imageset per image, Android res/ density buckets, Flutter asset folders with the pubspec lines), plus a viewer and a ledger. An image or character set exports as icons; an illustration set exports its scenes whole, for the illustrations in an app or site. One export per call: one batch of a set (a set that grew over several calls is exported batch by batch; the trees merge by folder) at one base size (a second size is a second call; names carry the size, so two sizes never collide). The files come from the set's full-resolution source, so each is the batch as it is currently delivered, scaled: an image or character set's size, canvas, sizing and margin all carry (edit_set changes them), and an illustration set's shape; no pixel comes from a delivered image. How large a batch exports crisp is its crispBaseSize: every generation and edit_set result states it, and list_recent_generations and get_generations report it. An image or character set takes base sizes from 16 to 256 (48 to 128 is the usual range for icons), its crisp size set by how many subjects or variations it holds at generation, and edits to its size, canvas, margin or sizing can move it; files up to 3x the 1x size (4x on Android) are always delivered, and where a density would enlarge a subject past its source pixels the ledger says so per tree ("soft": some blur) and by how much, never withholding a file. An illustration set takes base sizes from 16 up to its crispBaseSize, a quarter of the longest side its scenes were drawn at, so its export is always crisp. Not available for sets generated before editing existed (they have no source).

### delete_generations

Permanently delete one or more of your generations before their download window closes: each one's download URL stops working, and its images, its prompt.json and the full-resolution source kept for edit_set and export_set are removed from Logospell's servers. Call it only when the user asks to delete generations: it cannot be undone, the credits they cost are not refunded, and a deleted generation can no longer be edited or exported. Only the API key that made a generation can delete it. A set that grew over several calls has one id per call (list_recent_generations and get_generations show them); pass them all to delete the whole set in one call. Ids that are not found are reported without failing the call, which fails only when nothing was deleted. Up to 50 ids per call. Without this, every generation is removed automatically when its download window closes. Costs no credits.

### delete_references

Permanently delete one or more references you created with create_reference: each one's image is removed from Logospell's servers and its ref_ token stops working in any later call. Call it only when the user asks to delete references: it cannot be undone. Only the API key that created a reference can delete it; list_references shows yours. Tokens that are not found are reported without failing the call, which fails only when nothing was deleted. Up to 50 tokens per call. Without this, a reference expires on its own 7 days after its last use or re-upload. Costs no credits.

## Links

- [Documentation](https://logospell.com/docs): every Logospell MCP tool at a glance, grouped by the kind of set it makes, each linking to its full reference
- [Connect](https://logospell.com/connect): setting up each MCP client
- [Image sets reference](https://logospell.com/docs/image-sets): parameters, style guidance, and tips for generate_image_set and extend_image_set
- [Character sets reference](https://logospell.com/docs/character-sets): parameters, writing variations, and tips for generate_character_set and extend_character_set
- [Illustration sets reference](https://logospell.com/docs/illustration-sets): parameters, supported sizes, writing scenes, and tips for generate_illustration_set and extend_illustration_set
- [Edit set reference](https://logospell.com/docs/edit): parameters for edit_set, the free re-delivery of an existing image, character or illustration set
- [Export set reference](https://logospell.com/docs/export): parameters for export_set, the free export of an existing set for the web, iOS, Android and Flutter: icons from an image or character set, whole illustrations from an illustration set
- [Logospell](https://logospell.com): pricing and API keys
- [Terms of service](https://logospell.com/terms): ownership of generated images, commercial use, and acceptable use
- [Privacy](https://logospell.com/privacy): what the service collects, retention, and your rights