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
- Open your account, go to API keys and select Create API key.
- Give the key a name, choose Live or Test, choose where its images go, and set its daily credit limit.
- 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=NwithPOST /api/v1/generations,Nup to 60. The answer comes as soon as the generation finishes, or afterNseconds with its status at that moment. Running out of time isn’t an error: the generation carries on. GET /api/v1/generations/{id}?wait=Nworks the same way for a generation you already started. Withoutwait, it answers straight away.- Without either, the
POSTanswers at once withstatus: "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
refundedshows how many. - Each key stops at its daily credit limit, counted per day in UTC.
GET /api/v1/accountshows how many credits you can spend, and the key’sused_today,daily_credit_capandresets_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 |