Skins

Generate a skin

Draws a 64x64 player skin from a description: the face, hair and clothes, with the second layer used for hair, collars and boots that stand off the body. Takes a few minutes; poll job (skin:<id>) at GET /jobs/{job}, then fetch the PNG.

Charged to the key owner's own credits, refunded in full if it fails. Takes a personal API key.

POST/skins

Body

promptstringrequiredmax 400 characters

Who it is.

namestring

Its name. Absent uses the prompt.

variantstringdefault "wide"

Arm width.

Options: wide, slim

Response · 202

Accepted. Poll job until it leaves generating.

idstringrequired

The skin's id.

namestringrequired

Its name.

variantstringrequired

Arm width: wide (Steve) or slim (Alex).

Options: wide, slim

statusstringrequired

Where its generation got to. A skin made in the Studio is ready.

Options: generating, ready, error

errorstringrequired

Why the generation failed. Null otherwise.

promptstringrequired

What it was generated from, if it was.

createdAtstringrequired

ISO 8601.

updatedAtstringrequired

ISO 8601.

jobstringrequired

Its job handle, skin:<id>.

Error codes

Branch on error.code, never on the message.

invalid_json400

The request body wasn't a JSON object.

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.

wrong_key_kind401

An MCP key sent to the REST API, or an API key sent to the MCP server. Each only opens its own.

insufficient_credits402

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

account_suspended403

The account is suspended, so its keys open nothing. message says until when, if the suspension has an end date.

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.

skin_limit_reached409

The account holds as many skins as it may. Delete one first.