Generating
Generate a dialog
Produces a dialog — the screen a server opens over the game with /dialog (Minecraft 1.21.6 and newer), drawn in Minecraft's own look: themed cards, switches, sliders and real clickable buttons.
The prompt is the whole brief. A director decides what the screen is — its title, its sections, its controls and its colours (from the pack's style guide when it has one) — and the layout is drawn from that. layout narrows which kind of screen it builds; omit it and the director picks.
One flat charge per dialog, refunded in full if it fails. Edit the result afterwards in the Studio's dialog editor.
/packs/{pack}/dialogsPath parameters
packstringrequiredThe pack's slug, as returned by the packs endpoints.
Body
promptstringrequiredWhat the screen is for, and what it should feel like.
namestringYour label. Absent uses the title the director gives it.
layoutstringWhich kind of screen to build. Omit for the director's choice.
- sidebar: Categories down the left, the chosen one on the right: stores, profiles, menus with sections.
- columns: Two to four things side by side to compare: ranks, kits, crates, plans.
- tiles: A grid of clickable cards with a state you can read at a glance: rewards, shops, perks.
- rows: A list of clickable rows with a value chip: settings, toggles, warps.
- guide: A page to read, with its contents down the left: rules, getting started, patch notes.
- simple: A few words and one or two buttons: notices, confirmations.
Options: sidebar, columns, tiles, rows, guide, simple
progressbooleandefault falseGive the screen a progress bar.
qrUrlstringmax 300 charactersA link to draw as a QR code on the screen, which also opens when the code is clicked. http(s), at most 300 characters.
referenceIdstringA reference image: the referenceId from POST /packs/{pack}/references, or one uploaded in the Studio.
referenceIdsarray of stringmax 5 entriesSeveral reference images instead of one, in order: referenceIds from POST /packs/{pack}/references. The director is shown every one and designs the screen after them. Send this or referenceId, not both.
useStyleGuidebooleandefault trueFollow the pack's style guide — its palette, its notes and its reference pictures. Defaults to true, so a pack with a style guide produces assets that match it without this field. Send false for one asset that should deliberately not match. A pack with no style guide, or one switched off, ignores this either way.
Response · 202
Accepted. The work runs asynchronously — poll job until it leaves generating.
idstringrequiredThe asset's id within the pack.
typestringrequiredWhat is generating. For an item, item or item3d.
Options: model, vehicle, mob, block, block_face, model_texture, item, item_model, item3d, armor, armor3d, gui, hud, dialog, icon, rank_tag, sound
kindstringrequiredThe file format it is stored as.
Options: texture, model, font, sound
statusstringrequiredAlways generating — nothing is finished when this returns.
packstringrequiredThe pack it was written into.
jobstringrequiredPoll this at GET /jobs/{job} until it leaves generating.
Error codes
Branch on error.code, never on the message.
invalid_request400Something in the body or query is wrong. message says what.
invalid_api_key401The key isn't one of ours, or it has been revoked.
missing_api_key401No Authorization: Bearer header was sent.
wrong_key_kind401An MCP key sent to the REST API, or an API key sent to the MCP server. Each only opens its own.
insufficient_credits402Not enough AI Credits to run this. Nothing was started or charged.
account_suspended403The account is suspended, so its keys open nothing. message says until when, if the suspension has an end date.
asset_limit_reached403The pack is at its asset limit.
forbidden403Valid key, but not permitted to do this in this pack.
plan_required403The key is valid, but its account's plan does not include the API.
not_found404No such pack, asset or job.