Skip to content
MakePixel

Pixel art API

Make pixel art from your own code. Send a description, get back true-pixel PNG, JSON, Aseprite and palette files.

Updated November 19, 2026

The MakePixel API makes pixel art from a description, the same way Generate does on the canvas. Send a request with an API key and you get back true-pixel images: one pixel is one pixel, drawn with a small palette.

Get an API key

  1. Open your account, go to API keys and select Create API key.
  2. Give the key a name, choose Live or Test, choose where its images go, and set its daily credit limit.
  3. Copy the key. It’s shown only this once. If you lose it, revoke it and create a new one.

A key acts as you and uses your credits. Keep it on your server: don’t put it in a web page, an app you hand out or a public repository. You can have up to 10 keys at a time, and revoking one stops it straight away.

Your first request

curl https://makepixel.ai/api/v1/generations \
  -H "Authorization: Bearer $MAKEPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"prompt":"a knight with a blue shield"}'

Prefer: wait=60 holds the request open until the images are ready, for up to 60 seconds:

{
  "id": "gen_…",
  "object": "generation",
  "livemode": true,
  "status": "succeeded",
  "credits": 2,
  "refunded": 0,
  "count": 1,
  "project": null,
  "images": [
    {
      "id": "img_…",
      "width": 48,
      "height": 56,
      "colors": 14,
      "palette": ["#1b1c2e", "#3b5dc9", "…"],
      "png": "https://makepixel.ai/api/v1/images/img_….png",
      "files": {
        "png": "https://makepixel.ai/api/v1/images/img_….png",
        "json": "https://makepixel.ai/api/v1/images/img_….json",
        "aseprite": "https://makepixel.ai/api/v1/images/img_….aseprite",
        "gpl": "https://makepixel.ai/api/v1/images/img_….gpl",
        "hex": "https://makepixel.ai/api/v1/images/img_….hex"
      }
    }
  ]
}

Get the image

File links need the same key:

curl -H "Authorization: Bearer $MAKEPIXEL_API_KEY" -o knight.png \
  "https://makepixel.ai/api/v1/images/img_….png?scale=8"
File What you get
.png The image at one pixel per pixel, transparent where the background was removed. Add ?scale=2 up to ?scale=16 for a bigger copy that stays crisp; the longer side stops at 4096 pixels
.json width, height, colors, palette, and pixels: one array per row, each value an index into palette, or -1 for a transparent pixel
.aseprite An Aseprite file with the image’s palette
.gpl The palette for GIMP, Aseprite and Krita
.hex The palette as hex colours, one per line, as Lospec uses

An image on a project is read as it is now: if you’ve drawn on it in MakePixel since, the files have your changes.

Parameters

POST /api/v1/generations takes a JSON body:

Field Default What it does
prompt required What to draw, in any language, up to 2,000 characters
count 1 How many images: 1, 2, 4 or 8
detail standard How fine the pixel art is: simple, standard or detailed
background transparent transparent: the subject on its own, cropped. keep: the whole picture, edge to edge, for scenes and backgrounds
project the key’s setting The id of one of your projects to put the images on

A field that isn’t in this table is refused.

Where images go. Without project, images go where the key says: onto its project, or nowhere (“No canvas”). With project, they go onto that project; it must be one of yours and not in the trash, and a key set to a project can only use that one. A project’s id is the part after /app/p/ in its address. Images on a project are placed in a free spot, stay with the rest of your work, and come with an editor_url that opens them on the canvas. Images made with no canvas are kept for 30 days and then deleted, so save the ones you want to keep.

The response

Every call about a generation answers with the same object. A new generation answers 202 while it’s still running and 200 once it has finished.

Field What it means
id The generation’s id, gen_…
status running, succeeded, failed or canceled (stopped on the canvas before it finished)
livemode false for a test key
credits Credits charged, after any refund
refunded Credits given back for images that never came
count How many images were asked for
project The project the images went onto, or null
editor_url Opens the generation on the canvas (on a project only)
images The images delivered so far, each with its size, palette and files
error.reason Why it failed, when status is failed (see Errors)

Waiting for the result

  • Send Prefer: wait=N with POST /api/v1/generations, N up to 60. The answer comes as soon as the generation finishes, or after N seconds with its status at that moment. Running out of time isn’t an error: the generation carries on.
  • GET /api/v1/generations/{id}?wait=N works the same way for a generation you already started. Without wait, it answers straight away.
  • Without either, the POST answers at once with status: "running"; ask for the generation again until it has finished.

Retrying safely

Send an Idempotency-Key header, 1 to 64 visible ASCII characters with no spaces, and a retry can’t make or charge for a second generation:

  • The same key with the same body answers with the generation the first request started, with Idempotent-Replayed: true.
  • The same key with a different body is refused with idempotency_mismatch.
  • If the first request with that key never started (for example, it ran out of credits), the key can’t be used again: send the retry with a new one.

Idempotency keys belong to the API key they were sent with. Without one, every request starts a new generation.

Price

  • Each image costs 2 credits, from the same credits you use in MakePixel: 8 images cost 16 credits.
  • Credits are taken when a generation starts. Credits for an image that isn’t delivered are given back, and refunded shows how many.
  • Each key stops at its daily credit limit, counted per day in UTC. GET /api/v1/account shows how many credits you can spend, and the key’s used_today, daily_credit_cap and resets_at.
  • Test keys don’t use credits.

Your usage history lists API charges as “Generate (API)” with the key’s name. Buy more credits on Plan & credits.

Test keys

A test key (mkp_test_…) goes through the same checks as a live key, but answers straight away with sample images, uses no credits and has livemode: false. The same description always gives the same samples. These descriptions act out the other outcomes:

prompt What you get
test:fail A failed generation, reason nothing_usable
test:refused A failed generation, reason content_refused
test:no_credits The 402 you get without enough credits

An account can make 1,000 test generations a day.

Errors

An error answers with an HTTP status and a body like this:

{
  "error": {
    "code": "payment_required",
    "message": "not enough credits",
    "request_id": "…",
    "details": { "reason": "insufficient_credits", "need": 8, "have": 3, "buy_url": "https://makepixel.ai/account/billing" }
  }
}

Act on code and details.reason; message is for people and may change. If you contact us about an error, include request_id.

Status reason What to do
400 none A field is missing, misspelt or out of range. details is a list of { path, message }, one for each problem
400 bad_idempotency_key Use 1 to 64 visible ASCII characters with no spaces
401 missing_key Send Authorization: Bearer <your key>
401 invalid_key The key is mistyped or was revoked. Create a new one in your account
401 account_suspended The account that owns the key is suspended. Contact us
402 insufficient_credits Buy credits at buy_url. need is what the request costs, have what you can spend now
403 credits_frozen Your credits are on hold while a payment dispute is open. Contact us
403 project_mismatch This key is set to another project. Leave out project, or use a key without a project
404 project_not_found The project isn’t yours, or it’s in the trash
404 none No generation or image with that id for this key
409 idempotency_mismatch This Idempotency-Key was used with a different body. Use a new key for a new request
409 idempotency_key_spent The first request with this key never started. Retry with a new key
429 key_daily_cap This key has reached its daily credit limit (cap; used so far today). It resets at resets_at; for a higher limit, create a key with a higher one
429 too_many_requests This key sent more than limit requests in a minute. Slow down
429 too_many_generations Your account is making as many generations as it can for now
429 too_many_failures Too many recent generations failed. Change the descriptions before you try again
429 output_limit You have 10,000 images stored with no canvas. Each is deleted 30 days after it was made; until then, put new ones on a project
503 none Generation isn’t available right now. Try again later

Every 429 says how long to wait: a Retry-After header and details.retry_after, both in seconds. Retry after that, not sooner.

A generation that fails says why in error.reason, and its credits are given back:

error.reason What to do
content_refused The description asks for something that isn’t allowed. Change it; sending it again will be refused again
nothing_usable No usable picture came back. Try again, or change the description
upstream_unavailable Generation was briefly unavailable. Try again in a little while

Limits

What Limit
Requests 120 a minute for each key
Generations running at once 4 for each account
Generations started 40 an hour and 200 a day for each account, including Generate in MakePixel
Test generations 1,000 a day for each account
Images stored with no canvas 10,000, each kept for 30 days
API keys 10 for each account
Daily credit limit Your choice for each key, up to 100,000
Waiting Up to 60 seconds for each request

Was this helpful?

Your game's art deserves one home.

Open a canvas and draw the first sprite. The rest of the game can move in when it's ready.

Start drawing