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.
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. | |
| 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 variation 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 variation far larger than the rest, fill scales each variation 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 variation 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 variation; neither: native size). | |
| sizing | No | How variations 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 variation stays small in its frame. fill scales each variation 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 variation smaller than the frame, which the result reports when it happens. | |
| 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). | |
| character | No | The character every image depicts, in words: who or what it is and how it looks (a mascot, a creature, a person, or a single product or object). Provide this, characterReferences, or both - the references show what it looks like, and this text adds details and, if a reference image shows more than one character, says which of them to draw. | |
| 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 character or variation descriptions. | |
| validation | No | How to handle the automatic character/variation check before generating. One of: suggest (the default) - if the character and variation 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-variation 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. | |
| variations | Yes | What the character is doing in each image, one entry per image: either a list of descriptions or objects with description and filename (e.g. [{"description": "waving hello", "filename": "waving.png"}]). Each entry is one isolated variation of the same character - its pose, action, expression, how strongly it feels it, and anything it holds or wears - not a scene or setting. Entries must be distinct: entries differing only in case, punctuation, or spacing are rejected as the same. Write each variation as plain text, with no list marker such as "1." or "-" in front, no square brackets, and no invisible characters. | |
| minimumMargin | No | Minimum margin in pixels around each variation. 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 variation and never falls below this (only the set's largest variation sits exactly on it); with fill sizing every variation touches it on one axis. | |
| characterReferences | No | Up to 3 reference images of the character every image depicts, alone or alongside the character text. 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. The set shows the character alone, not the rest of the reference images. To add more variations to a set later, use extend_character_set. Provide at least one of character and characterReferences. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | The delivered image format. | |
| images | No | The generated images: each one's file name inside the zip, its variation, 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. | |
| character | No | ||
| expiresAt | No | When the download URL expires. | |
| remaining | No | Credits remaining after this call. | |
| background | No | The background color used, or transparent. | |
| manifestURL | No | ||
| rejectedCharacter | No | Present only when the request was rejected because the character text does not appear to describe a character: the submitted text. No generation ran and nothing was charged; revise it (or drop it and use characterReferences) and resubmit. | |
| rejectedVariations | No | Present only when the request was rejected because some variations do not appear to describe distinct, drawable variations: the exact rejected entries. No generation ran and nothing was charged; revise or remove them and resubmit. | |
| suggestedCharacter | No | Present only on a validation suggestion: the cleaned character text, for review. An empty string means the cleanup removed the character text entirely (nothing in it said who or what the character is) - replace it, or use characterReferences. Absent when the character text was not checked (references only, or an extension). No generation ran and nothing was charged. | |
| suggestedVariations | No | Present only on a validation suggestion: the cleaned variation list, one entry per image. Adopt these, or resubmit your own wording with validation set to skip. |