Generate design candidates
design_generate_candidatesGenerate several candidate designs for ONE brief so the user can pick.
A design usually starts here: the user describes what they want and gets
three options back. For a single design, or to refine one they already
picked, use design_start_for_order.
prompt MUST be the user's own description of the piece. Never synthesise a
brief, and never treat their choice of the design route as a description of
the artwork: if they have not said what they want, ask before calling this.
Each call spends count real generations, so a guessed brief wastes them all
and shows the user designs for something they never asked for.
Pass the order_id and the design brief; it provisions count designs
(default 3) against the order's
real geometry, generates each in parallel, and returns them as candidates
— each with a design_id, a short summary, a design_url, and
thumbnails. Pass item_id to design one item; it is required when the
order has several items (OrderItemRequiredError lists them). Each item
keeps its own design, so the items of an order can be designed side by side.
On an order with several items, an item whose design is already attached
fails with DesignAttachedError, because that design is final. An item
whose uploaded file has a submitted page mapping fails with
UploadMappingSubmittedError, because that file prints.
Present every candidate to the user as a numbered markdown link to its
thumbnail (and design_url) so they SEE each option — never only the text
summary — and use those URLs EXACTLY as returned (never build or guess one).
Number them in the order returned: the user may reply by position ("design
nr 2"), so map that number back to candidates[n-1].design_id yourself.
A candidate with thumbnails_pending: true has no preview yet: its image is
still rendering, and it may not become available. Still offer it and link its
design_url. Tell the user that the preview is still rendering and may not be
available, and that they can choose the design or open it in the editor anyway.
Do not say that the preview will appear.
Then let the USER choose and call design_pick_candidate with their chosen
design_id before any design_chat; the unpicked candidates are dropped.
While a batch is unpicked, a new call fails with CandidatePendingError.
If the customer rejected every candidate, offer a new batch. Call again with
discard_unpicked=true only after they say yes: it drops the unpicked batch.
Each order item gets at most 3 batches (CandidateBatchLimitError).
Returns a job — poll with poll_job until SUCCEEDED.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"session_id": "<session_id>",
"order_id": "<order_id>",
"prompt": "<prompt>"
},
"name": "design_generate_candidates"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| prompt | Yes | ||
| item_id | No | ||
| order_id | Yes | ||
| session_id | Yes | ||
| discard_unpicked | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |