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

EndpointDoesCredits
POST /v1/imagesPixel art from a promptpixelz 3; gemini by quality: fast 2, standard 4, pro 8; gpt by quality: fast 2, standard 3, pro 5
POST /v1/editsA sprite with one thing changed3 credits
POST /v1/stylesA new object in a reference sprite's style3 credits
POST /v1/directionsA sprite facing 8 directions on one 3×3 sheet5 credits
POST /v1/pixelizeAn image snapped to its pixel gridfree
POST /v1/remove-backgroundA transparent backgroundfree
POST /v1/effectsAn animated pixel effect from a descriptionabout 6
POST /v1/animationsA sprite, animatedv1.1 8, v1.5 11
GET /v1/jobs/{id}A job's status and resultfree
POST /v1/uploadsAn upload for a local filefree
GET /v1/creditsCredits left this monthfree

POST /v1/images

FieldTypeNotes
promptstringRequired, 3–2000 characters. What to draw.
size16 | 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_backgroundbooleanCut the subject out. Default true.
colors"auto" | 2–64Palette 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_imagestringOptional, 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

FieldTypeNotes
imagestringRequired. The sprite at its own pixel size, up to 256×256; an enlarged sprite is snapped to its grid first.
instructionstringRequired, 3–500 characters. One change, said plainly: "make it a blue crystal", "replace the sword with a battle axe", "overhead attack".
transparent_backgroundbooleanKeep 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

FieldTypeNotes
reference_imagestringRequired. The sprite whose style, palette and outline to copy, up to 256×256 at its own pixel size.
promptstringRequired, 2–500 characters. One object, named plainly: "kite shield", "alien rifle".
size16 | 24 | 32 | 48 | 64 | 96 | 128The 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

FieldTypeNotes
imagestringRequired. 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

FieldTypeNotes
imagestringRequired. An https URL, an upload id or base64 data.
colors"auto" | 2–64Palette size. Default "auto".
remove_backgroundbooleanAlso make the background transparent. Default false.
save_to_assetsbooleanAlso keep the result in your PixelZ Assets. Default false.

POST /v1/remove-background

FieldTypeNotes
imagestringRequired. An https URL, an upload id or base64 data.
save_to_assetsbooleanAlso keep the result in your PixelZ Assets. Default false.

POST /v1/effects

FieldTypeNotes
descriptionstringRequired, 3–400 characters. What happens and how it moves.
width16–96Canvas width in pixels. Optional; one side alone gives a square, none lets the model pick.
height16–96Canvas 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

FieldTypeNotes
imagestringRequired. The sprite, at most 256×256.
motionstringRequired, 3–300 characters, e.g. "walking to the right, arms swinging".
frames4 | 6 | 8Frames 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:

roomFramesSprite
noneThe size of the image sentAs sent. The default: add any space yourself.
aroundSquare: 1.5× the sprite's longer side, rounded up to a multiple of 8Trimmed to its opaque pixels and centred. Fits characters and things alike, side view or isometric.
aboveThe same squareTrimmed, 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"
FieldNotes
idThe job's id.
toolgeneration, pixelize, removeBackground, effect or animation.
statusrunning, done or failed.
creditsWhat the job cost; while it runs, what it was charged. 0 when it failed and was refunded.
outputsThe files: kind (image, strip or gif), url, width, height.
framesFor a strip: frameWidth, frameHeight, frameCount, and for effects fps and loop.
errorWhy the job failed.
savedtrue when save_to_assets kept the result. Generated images are always in your Assets.
retry_after_secondsOnly 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" }
StatusMeaning
400The body is not valid JSON, a field is missing or out of range, or an upload was sent without a file.
401No key, or a key that is unknown or revoked.
402Not enough credits left this month.
404No such job, or the upload address is unknown, expired or already used.
409Two files reached the same upload address at once.
413The uploaded file is larger than 2 MB.
422The image was refused or the tool failed. The message says why.
429Too 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.
500Something 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 credits shows 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_assets stay in PixelZ until you delete them.

Working with an AI agent? The MCP server offers the same tools with the same key.