REST API

The REST API runs the same tools as the MCP server, for scripts, build pipelines and your own apps. It is available on paid plans and uses your plan's credits.

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.

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

POST /v1/images

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/pixelize

POST /v1/remove-background

POST /v1/effects

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

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.

Jobs

Pixelize, remove-background and effects answer with the finished job. Images and animations answer with a job that is still running: poll it every 10 seconds or so until its status is done or failed.

curl https://api.pixelz.io/v1/jobs/<id> -H "Authorization: Bearer $PIXELZ_API_KEY"

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.

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 lasts 60 minutes and only your account can use it.

Errors

A failed request answers with a status and a message:

{ "error": "Use a public https URL for the image" }

Credits and limits

• Prices are the same as in the app. A request that fails is refunded.
• An effect is billed by what the model used, about 4 credits. You need 14 available to start one.
• 60 requests a minute per account across all keys, in bursts of up to 20.
• 4 requests and 10 jobs running at once, 1000 calls of the free tools a day, 100 uploads open at once.
• Jobs and their files are deleted after 30 days. Generated images, animations and results sent with save_to_assets stay in your Assets until you delete them.