Generating

Generate an item

Produces a texture named item:<name> for a 2D sprite, or a model for a 3D one — the response's kind and job say which.

Omit target (or send null) for an item of your own; give a vanilla item id to reskin it. Reskinning one this pack already reskins answers 409: change it in the Studio rather than overwriting it blind. variant needs a target and Minecraft 1.21.4 or newer.

POST/packs/{pack}/items

Path parameters

packstringrequired

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

Body

promptstringrequired

What to draw or build.

targetstring

A vanilla item to reskin. Null or absent means a new item.

shapestringdefault "2d"

A flat sprite, or real geometry.

Options: 2d, 3d

sizeinteger16–128

Sprite edge length. 2D only.

namestring

Your label. Falls back to the prompt.

variantboolean

A custom-model-data variant of target rather than a full reskin.

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.