Generating

Generate the in-game HUD

Produces a texture named gui:<name>, like a GUI — but where a GUI is one screen a plugin opens, this is the overlay drawn over the world while nothing is open at all: hearts, hunger, armour, air, the hotbar, the crosshair, the experience bar and the boss bar.

There are two sets, chosen with hud. hud is what you read while you play; overlays is the full-screen layers — the vignette at the edge of your vision, the Nausea swirl. A pack may hold one of each.

One asset, many files. A HUD set replaces up to 82 real vanilla sprites and is edited afterwards as a single sheet. A pack may hold ONE of each set; a second is refused with conflict.

Image spend is per GROUP, not per file. Each group costs one image call, and everything in it is derived from that one drawing — one heart becomes all forty-four of vanilla's moods, fills and damage flashes, and one strip becomes the experience bar and every boss bar colour. Pass groups to narrow what you pay for.

The crosshair is picked, not described. Vanilla’s stays readable by inverting whatever is behind it, which a resource pack cannot do, so this one is drawn light with a dark outline from a fixed set of shapes. crosshair chooses which; a prompt would not survive contact with a snowfield.

POST/packs/{pack}/hud

Path parameters

packstringrequired

The pack's slug, as returned by the packs endpoints.

Body

promptstringrequired

What the HUD is made of, and what its pips are. Applied to every group.

namestring

Your label.

hudstringdefault "hud"

Which set to make. hud is the overlay along the bottom and middle of the screen; overlays is the full-screen layers (the vignette, the Nausea swirl). They are separate assets and a pack may hold one of each.

Options: hud, overlays

groupsarray of string

Which parts to make — one image call each. Omit for everything available in the chosen set. The enum below is the union across both sets; a group belonging to the other one is refused, as is an unknown or held id. Nothing is ever silently skipped.

crosshairstringdefault "cross"

Which reticle shape to draw. Composed, so it costs no image call.

Options: cross, dot, bracket, circle, chevron

referenceIdstring

A reference image already uploaded in the Studio. There is no API endpoint to upload one yet.

referenceStrengthnumber0.05–0.95

How closely to follow the reference. Clamped to this range rather than rejected.

Response · 202

Accepted. The work runs asynchronously — poll job until it leaves generating.

idstringrequired

The asset's name within the pack.

kindstringrequired

Which store the generated asset lands in.

Options: texture, model, font, sound

statusstringrequired

Always generating — nothing is finished when this returns.

packstringrequired

The pack it was written into.

jobstringrequired

Poll this at GET /jobs/{job} until it leaves generating.

Error codes

Branch on error.code, never on the message.

invalid_request400

Something in the body or query is wrong. message says what.

invalid_api_key401

The key isn't one of ours, or it has been revoked.

missing_api_key401

No Authorization: Bearer header was sent.

insufficient_credits402

Not enough AI Credits to run this. Nothing was started or charged.

asset_limit_reached403

The pack is at its asset limit.

forbidden403

Valid key, but not permitted to do this in this pack.

plan_required403

The key is valid, but its account is on Starter. The API needs a paid plan.

not_found404

No such pack, asset or job.

conflict409

That vanilla target is already reskinned in this pack. Change it in the Studio rather than overwriting it.

unavailable503

The feature behind this endpoint is switched off.