API & MCP
REST API
PixelZ REST API reference: authentication, endpoints, jobs, errors and limits for image generation, pixelize, background removal, effects and animation.
The REST API runs the same tools as the MCP server, for scripts, build pipelines and your own apps. It works on every plan, the free one included, and uses your account's credits.
Quick setup for agents
Copy the setup and paste it into Claude, Codex, Cursor or any agent that can make HTTP requests. It uses your key when it has one, and otherwise sends you the two links to get one.
Authentication
Create a key in Settings → API & MCP and send it as a bearer token with every request:
Authorization: Bearer pz_…Base URL: https://api.pixelz.io. Requests and responses are JSON. Call the API from a server or script, never from a web page: browsers are blocked, and the key must stay secret.
Quick start
Turn an image into pixel art:
curl https://api.pixelz.io/v1/pixelize \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "https://example.com/knight.png", "colors": 16, "remove_background": true}'Every tool answers with a job. Download the file from the url of its output:
{
"id": "k57f3d9x2c8a1b0e4r6t7y8u9i0o",
"tool": "pixelize",
"status": "done",
"credits": 0,
"outputs": [
{ "kind": "image", "url": "https://…/api/storage/…", "width": 32, "height": 32 }
]
}Endpoints
| Endpoint | Does | Credits |
|---|---|---|
POST /v1/images | Pixel art from a prompt | pixelz 3; gemini by quality: fast 2, standard 4, pro 8; gpt by quality: fast 2, standard 3, pro 5 |
POST /v1/edits | A sprite with one thing changed | 3 credits |
POST /v1/styles | A new object in a reference sprite's style | 3 credits |
POST /v1/directions | A sprite facing 8 directions on one 3×3 sheet | 5 credits |
POST /v1/pixelize | An image snapped to its pixel grid | free |
POST /v1/remove-background | A transparent background | free |
POST /v1/effects | An animated pixel effect from a description | about 6 |
POST /v1/animations | A sprite, animated | v1.1 8, v1.5 11 |
GET /v1/jobs/{id} | A job's status and result | free |
POST /v1/uploads | An upload for a local file | free |
GET /v1/credits | Credits left this month | free |
POST /v1/images
| Field | Type | Notes |
|---|---|---|
prompt | string | Required, 3–2000 characters. What to draw. |
size | 16 | 24 | 32 | 48 | 64 | 96 | 128 (gemini, gpt: 16 | 32 | 64 | 128 | 256 | 512) | Target longer side in pixels. Default 64. pixelz draws exactly this size; gemini and gpt keep the grid they drew, which can differ, so read the output's width and height. |
aspect_ratio | "1:1" | "16:9" | "9:16" | Default "1:1". pixelz draws 1:1 only. |
transparent_background | boolean | Cut the subject out. Default true. |
colors | "auto" | 2–64 | Palette size. Default "auto". |
engine | "pixelz" | "gemini" | "gpt" | The image model. Default "pixelz": PixelZ Core v1, our own pixel-art model, square sprites up to 128. Send "gemini" (Nano Banana) or "gpt" (GPT Image 2.5 Flare) for a bigger or non-square image. |
quality | "fast" | "standard" | "pro" | gemini and gpt only. Default "standard". Credits: pixelz 3; gemini by quality: fast 2, standard 4, pro 8; gpt by quality: fast 2, standard 3, pro 5. |
asset_type | "character" | "creature" | "item" | "food" | "effect" | "vehicle" | "ui" | "portrait" | "tile" | "background" | pixelz only, optional. What kind of picture it is; a tile or a background fills the picture and is never transparent. |
reference_image | string | Optional, gemini and gpt only. An image to follow for style or subject. For pixelz, use the style reference endpoint. |
curl https://api.pixelz.io/v1/images \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "a knight with a blue cape, idle pose, side view", "size": 64}'Answers 202 with a running job; it usually finishes within two minutes. The image is also saved to your Assets.
POST /v1/edits
| Field | Type | Notes |
|---|---|---|
image | string | Required. The sprite at its own pixel size, up to 256×256; an enlarged sprite is snapped to its grid first. |
instruction | string | Required, 3–500 characters. One change, said plainly: "make it a blue crystal", "replace the sword with a battle axe", "overhead attack". |
transparent_background | boolean | Keep the sprite cut out. Default: true when the image has transparent pixels; false edits the whole picture. |
curl https://api.pixelz.io/v1/edits \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "https://example.com/pink-blaster.png", "instruction": "make it a blue crystal"}'Answers 202 with a running job. A pose gets a bigger canvas so the character keeps its size. How to write good edits: Edit.
POST /v1/styles
| Field | Type | Notes |
|---|---|---|
reference_image | string | Required. The sprite whose style, palette and outline to copy, up to 256×256 at its own pixel size. |
prompt | string | Required, 2–500 characters. One object, named plainly: "kite shield", "alien rifle". |
size | 16 | 24 | 32 | 48 | 64 | 96 | 128 | The new sprite's size in pixels. Default 64. |
curl https://api.pixelz.io/v1/styles \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reference_image": "https://example.com/crystal-sword.png", "prompt": "kite shield", "size": 96}'Answers 202 with a running job; the sprite comes back exactly size×size with a transparent background.
POST /v1/directions
| Field | Type | Notes |
|---|---|---|
image | string | Required. A character or an object cut out on a transparent background, at its own pixel size, up to 128×128; an enlarged sprite is snapped to its grid first. |
curl https://api.pixelz.io/v1/directions \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "https://example.com/knight-32.png"}'Answers 202 with a running job. The result is one 3×3 sheet: back views on the top row, side views in the middle, front views at the bottom, the centre cell empty; every view stands on the same baseline in equal cells. More in 8 Directions.
POST /v1/pixelize
| Field | Type | Notes |
|---|---|---|
image | string | Required. An https URL, an upload id or base64 data. |
colors | "auto" | 2–64 | Palette size. Default "auto". |
remove_background | boolean | Also make the background transparent. Default false. |
save_to_assets | boolean | Also keep the result in your PixelZ Assets. Default false. |
POST /v1/remove-background
| Field | Type | Notes |
|---|---|---|
image | string | Required. An https URL, an upload id or base64 data. |
save_to_assets | boolean | Also keep the result in your PixelZ Assets. Default false. |
POST /v1/effects
| Field | Type | Notes |
|---|---|---|
description | string | Required, 3–400 characters. What happens and how it moves. |
width | 16–96 | Canvas width in pixels. Optional; one side alone gives a square, none lets the model pick. |
height | 16–96 | Canvas height in pixels. Optional. |
Takes up to a minute. The job has two outputs, a horizontal strip PNG and a looping gif; frames describes the strip.
POST /v1/animations
| Field | Type | Notes |
|---|---|---|
image | string | Required. The sprite, at most 256×256. |
motion | string | Required, 3–300 characters, e.g. "walking to the right, arms swinging". |
frames | 4 | 6 | 8 | Frames in the loop. Default 6; an odd number is rounded up. |
model | "v1.1" | "v1.5" | Default v1.1, the best at loops (walk and run cycles, idles). v1.5 costs more and is a bit slower, but follows unusual or very specific motions much more closely. |
room | "none" | "around" | "above" | Space added around the sprite before it is animated. Default none: animated as sent. See below. |
curl https://api.pixelz.io/v1/animations \
-H "Authorization: Bearer $PIXELZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "https://example.com/knight-32.png", "motion": "walking to the right", "frames": 6}'Answers 202 with a running job; it takes 1–3 minutes. The output is a strip, and frames describes it.
Room to move
The frames are the size of the canvas the model gets. A sprite trimmed tight leaves no space for a jump, a dash or a big swing, so the model squashes the figure instead of moving it. room adds the space for you, on a sprite with a transparent background:
| room | Frames | Sprite |
|---|---|---|
none | The size of the image sent | As sent. The default: add any space yourself. |
around | Square: 1.5× the sprite's longer side, rounded up to a multiple of 8 | Trimmed to its opaque pixels and centred. Fits characters and things alike, side view or isometric. |
above | The same square | Trimmed, centred across, feet on the bottom row of every frame: more room for a side-view jump. |
A 32×32 character (17×30 opaque) comes back in 72×72 frames (2.2 × 30 = 66, rounded up to 72), at most256, the most the model takes. With around the sprite's centre sits at the frame's centre, so anchor it there; with above anchor it at the bottom centre. Read the size from frames, not from the sprite you sent. An image without transparency is always animated as sent.
Jobs
Pixelize, remove-background and effects answer with the finished job. Images, edits, styles and animations answer with a job that is still running: get it until its status is done or failed. With ?wait= (up to 50 seconds) the request answers as soon as the job ends, so you don't need to poll in between. A generation that hasn't ended after 20 minutes, or an animation after 2 hours, fails; its result may still turn up in the app.
curl "https://api.pixelz.io/v1/jobs/<id>?wait=50" -H "Authorization: Bearer $PIXELZ_API_KEY"| Field | Notes |
|---|---|
id | The job's id. |
tool | generation, pixelize, removeBackground, effect or animation. |
status | running, done or failed. |
credits | What the job cost; while it runs, what it was charged. 0 when it failed and was refunded. |
outputs | The files: kind (image, strip or gif), url, width, height. |
frames | For a strip: frameWidth, frameHeight, frameCount, and for effects fps and loop. |
error | Why the job failed. |
saved | true when save_to_assets kept the result. Generated images are always in your Assets. |
retry_after_seconds | Only when a ?wait= was refused because too many waits ran at once: get the job again after this many seconds. |
Images
- PNG or JPEG, as a public https URL, an upload id or base64 data (a data URL works too).
- Up to 2 MB and 1024×1024 pixels. Interlaced PNGs are not accepted.
- A URL must be https on a public host name (no IP address, no port other than 443), with at most 3 redirects.
Uploading a file
To send a file from disk, open an upload, send the file to the address you get, and pass the returned id as image:
curl -X POST https://api.pixelz.io/v1/uploads -H "Authorization: Bearer $PIXELZ_API_KEY"
# { "image": "upload:k9…", "upload_url": "https://api.pixelz.io/v1/uploads/3f9c…", "expires_in_minutes": 60 }
curl -T knight.png "https://api.pixelz.io/v1/uploads/3f9c…"
# { "image": "upload:k9…", "width": 256, "height": 256 }
curl https://api.pixelz.io/v1/remove-background \
-H "Authorization: Bearer $PIXELZ_API_KEY" -H "Content-Type: application/json" \
-d '{"image": "upload:k9…"}'The address takes one file and needs no key, so keep it private. An upload expires 60 minutes after you open it; until then its id works in any number of calls, from your account only.
Errors
A failed request answers with a status and a message:
{ "error": "Use a public https URL for the image" }| Status | Meaning |
|---|---|
| 400 | The body is not valid JSON, a field is missing or out of range, or an upload was sent without a file. |
| 401 | No key, or a key that is unknown or revoked. |
| 402 | Not enough credits left this month. |
| 404 | No such job, or the upload address is unknown, expired or already used. |
| 409 | Two files reached the same upload address at once. |
| 413 | The uploaded file is larger than 2 MB. |
| 422 | The image was refused or the tool failed. The message says why. |
| 429 | Too many requests, too many running at once, or PixelZ is busy. Wait and retry; a Retry-After header says how many seconds, except when too many are running at once: wait for one to finish. |
| 500 | Something went wrong on our side. Retry later. |
Credits and limits
- Prices are the same as in the app. A request that fails is refunded, with two exceptions: a failed effect keeps what its model used, and an image that was generated but couldn't be finished stays charged and can be retried in the app; a job that times out keeps what was charged, and its result may still arrive in the app. The job's
creditsshows what was kept. - An effect is billed by what the model used, about 6 credits. You need 8 available to start one.
- 60 requests a minute per account across all keys, in bursts of up to 20.
- 4 requests and 10 jobs (images and animations) running at once, 1000 calls of the free tools (pixelize, remove-background) per 24 hours, 100 uploads open at once.
- Jobs and their files are deleted after 30 days, effects included. Generated images, animations and results sent with
save_to_assetsstay in PixelZ until you delete them.
Working with an AI agent? The MCP server offers the same tools with the same key.